MIMEDEFANG-MULTIPLEXOR(8)

NAME
mimedefang-multiplexor - Process pool controller for mail filters.

SYNOPSIS
mimedefang-multiplexor [options]

DESCRIPTION
mimedefang-multiplexor manages a pool of Perl processes for scanning e-mail. It is designed to work in conjunction with mimedefang(8) and mimedefang.pl(8). mimedefang-multiplexor opens a UNIX-domain socket and listens for requests for work from mimedefang. As requests come in, mimedefang-multiplexor creates Perl processes as needed to scan mail. The Perl processes are not killed when scanning is completed, but continue to run in a loop. Perl processes are re-used for subsequent e-mail messages. This eliminates the large overhead of starting a new Perl process for each incoming message. To avoid memory leaks, the Perl processes are killed after they have handled some number of scans,

OPTIONS

-U user
    Runs the multiplexor as user rather than root. All filters are run as user, not root as well. We strongly recommend that you create a dedicated MIMEDefang user and run the multiplexor as that user. IMPORTANT: If you use the -U option for the multiplexor, you must use the identical -U option for mimedefang as well, or filtering will fail!

-m minSlaves
    The minimum number of Perl processes to keep running at all times. The default is zero.

-x maxSlaves
    The maximum number of Perl processes to run simultaneously. If a request comes in and all processes are busy, a temporary failure is signalled to the SMTP peer.

-r maxRequests
    The maximum number of requests a given process handles before it is killed and a replacement started. The default is 100.

-i idleTime
    The idle time in seconds after which to kill of excess Perl processes. That is, if the process is idle for longer than this time, and there are more than minSlaves running, the process is killed. Note that this is implemented as a timer which ticks every idleTime seconds; therefore, processes may be idle for up to twice this time before they are killed. The default for idleTime is 300 seconds.

-b busyTime
    The longest a Perl process is allowed to spend scanning an e-mail before it is declared hung up and killed. The default is 300 seconds.

-c cmdTime
    The timeout for communication between mimedefang-multiplexor and mimedefang, or between mimedefang-multiplexor and a Perl scanning process. The default is 10 seconds. This timeout should be kept quite short.

-w waitTime
    When mimedefang-multiplexor starts the initial slaves, or needs to bring the number of running slaves up to the number defined by the -m option, it does not start all the slaves at once, because this could overload your server. Instead, it starts one slave every waitTime seconds. The default value for waitTime is 3.

-W waitTime
    If you use this option, mimedefang-multiplexor will never activate a slave until waitTime seconds have elapsed since the last slave activation. This could result in mail being tempfailed if slave activations do not keep pace with incoming mail. However, it may be preferable to tempfail mail rather than allow the load on your server to spike up too quickly. The default value for this option is 0, meaning that mimedefang-multiplexor will start slaves as quickly as necessary to keep up with incoming mail.

-s pathName
    The UNIX-domain socket on which mimedefang-multiplexor listens for request. This should be specified as an absolute pathname.

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

-f filter_path
    Normally, mimedefang-multiplexor 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-multiplexor 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.

-l  Log certain events using syslog. Normally, the multiplexor does not log any information.

-d  Write debugging information about event-handling code in /var/log/mimedefang-event-debug.log. This is only of use to people debugging mimedefang-multiplexor.

-R kbytes
    Limits the resident-set size of the slave filter processes to kbytes kilobytes. This limit is not supported on all operating systems; it is known to work on Linux.

-M kbytes
    Limits the total memory space of slave filter processes to kbytes kilobytes. This limit is supported on all operating systems which support the setrlimit(2) system call. This should include most modern UNIX systems. We recommend that you monitor your slave filter processes and get a feel for how much memory they use. You should then limit the memory to two or three times the worst-case that you have observed. This can help mitigate denial-of-service attacks which use complicated MIME messages to force mimedefang.pl to consume lots of memory.

-h  Print usage information and exit.

-t filename
    Log statistical information to filename. See the section STATISTICS for more information.

-T  Log statistical information using syslog(2). You may use any -t and -T together, in which case statistical information is logged in a file and using syslog.

-u  Flush the statistics file after every write. Normally, mimedefang-multiplexor does not flush the file; this is the best choice for minimizing disk I/O on a busy mail server. However, if you wish to watch statistics entries in real-time, you should enable flushing.

STATISTICS
With the -t option, mimedefang-multiplexor logs certain events to a file. This file can be post-processed to gather statistics about the multiplexor. You can use it to tune the number of slaves you run, adjust timeouts, and so on.

Each line of the file looks like this:
	YYYY/MM/DD:HH:MM:SS timestamp event key=val key=val...
Here, YYYY/MM/DD:HH:MM:SS is the local time of day. Timestamp is the number of seconds since January 1, 1970. Event is the name of an event. The valid events are:

StartSlave
    A slave process has been started.

KillSlave
    A slave process has been killed.

ReapSlave
    A dead slave process has been reaped. It is possible to have a ReapSlave event without a previous KillSlave event if the slave process terminated abnormally.

StartFilter
    A slave process has begun filtering an e-mail message.

EndFilter
    A slave process has finished filtering an e-mail message.

The possible keys in the key=value pairs are:

slave=n
    The slave involved in the event. Every slave is identified by a small integer.

nslaves=n
    The total number of running slaves immediately after the event happened.

nbusy=n
    The number of busy slaves (slaves which are processing an e-mail message) immediately after the event happened.

reason="string"
    The reason for a StartSlave or KillSlave event. (Present only for these events.)

numRequests=n
    The number of e-mails processed by the slave. Present only for an EndFilter event.

If you send the mimedefang-multiplexor process a SIGHUP signal (kill -1 pid), it closes and reopens the statistics file. This is useful during log file rotation.

If you send the mimedefang-multiplexor process a SIGINT signal (kill -INT pid), it terminates all active-but-idle slaves. Also, any active-and-busy slaves terminate as soon as they finish filtering the current message. This is useful to force a reread of the filter rules file without stopping and restarting Sendmail.

If you send the mimedefang-multiplexor process a SIGTERM signal (kill pid), it terminates all slaves and exits immediately.

AUTHOR
mimedefang-mulitplexor 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(8), mimedefang-protocol(7)