Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help

       mimedefang-multiplexor -	Process	pool controller	for mail filters.

       mimedefang-multiplexor [options]

       mimedefang-multiplexor manages a	pool of	Perl processes for scanning e-
       mail.  It is designed to	work in	 conjunction  with  mimedefang(8)  and

       mimedefang-multiplexor  opens  a	UNIX-domain socket and listens for re-
       quests for work from mimedefang.	 As requests come in,  mimedefang-mul-
       tiplexor	 creates Perl processes	as needed to scan mail.	 The Perl pro-
       cesses 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.

       -U user
	      Runs the multiplexor as user rather than root.  This  option  is
	      mandatory, and must match	the -U option supplied to mimedefang.

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

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

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

       -i idleTime
	      The idle time in seconds after which to kill of excess Perl pro-
	      cesses.  That is,	if the process is idle for  longer  than  this
	      time, and	there are more than minWorkers 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.

       -V maxLifetime
	      The  maximum lifetime in seconds of a worker before it is	killed
	      and a replacement	started.  The default is -1,  which  signifies
	      no  maximum lifetime.  Note that the lifetime check is done only
	      when a worker becomes idle after a request, or  every  time  the
	      idle-timeout check is made.  On a	very quiet system, workers may
	      live for longer than maxLifetime by as much as  idleTime.	  Note
	      also  that  the  lifetime	 is  measured not from when the	worker
	      started running, but from	when it	was assigned  its  very	 first
	      request.	 A completely-idle worker that has never processed any
	      requests will not	be terminated by the maxLifetime setting.

       -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
	      120 seconds.

       -Z     This option specifies that the  multiplexor  should  accept  and
	      process "status updates" from busy workers.  Note	that this con-
	      sumes one	extra file descriptor per worker, plus a small	amount
	      of CPU time per status update.

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

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

       -W waitTime
	      If  you use this option, mimedefang-multiplexor will never acti-
	      vate a worker until waitTime seconds have	elapsed	since the last
	      worker  activation.   This could result in mail being tempfailed
	      if worker	activations do not keep	pace with incoming mail.  How-
	      ever,  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 workers as quickly as necessary to keep up  with  in-
	      coming mail.

       -z spooldir
	      Set the spool directory to spooldir.  If this option is omitted,
	      the spool	directory defaults to /var/spool/MIMEDefang.

       -s pathName
	      The UNIX-domain socket on	which  mimedefang-multiplexor  listens
	      for requests.  This should be specified as an absolute pathname.
	      If this option is	not supplied, it defaults to mimedefang-multi-
	      plexor.sock under	the spool directory.

       -a socket
	      A	 socket	for listening for requests.  This is similar to	the -s
	      socket, except that a restricted set of requests are  processed.
	      On  this socket, the multiplexor will only process requests ask-
	      ing for status; it will not accept any commands to  do  scanning
	      or  that	would  consume a worker.  See the SOCKET SPECIFICATION
	      section for the format of	socket.

       -p fileName
	      Causes mimedefang-multiplexor to write its process-ID (after be-
	      coming  a	daemon)	to the specified file.	The file will be owned
	      by root.

       -o fileName
	      Causes mimedefang-multiplexor to use fileName as a lock file  to
	      avoid multiple instances from running.  If you supply -p but not
	      -o, then mimedefang-multiplexor constructs a lock	 file  by  ap-
	      pending  ".lock"	to the pid file.  However, this	is less	secure
	      than having a root-owned pid file	in a root-owned	directory  and
	      a	 lock  file writable by	the user named by the -U option.  (The
	      lock file	must be	writable by the	-U user.)

       -f filter_path
	      Normally,	mimedefang-multiplexor executes	a Perl	filter	script
	      called 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 pro-
	      tocol documented in mimedefang-protocol(7); see that manual page
	      for details.

	      Note  that  the  -f  option does not specify the "filter"	to use
	      with;  instead,  it  specifies  the  program  for
	      mimedefang-multiplexor  to execute.  You almost certainly	should
	      not use this option unless you  wish  to	replace
	      with your	own program.

       -F rules_path
	      Specifies	 the  path  to the filter rules.  By default, /usr/lo-
	      cal/etc/mimedefang/mimedefang-filter is used.  If	you use	the -F
	      option,  its  value is passed to the underlying Perl filter pro-
	      gram using -f.

       -l     Log certain events, including the	output of  the	Perl  workers'
	      standard-error,  using  syslog.	Normally, the multiplexor does
	      not log much 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 worker 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	 worker	 filter	 processes  to
	      kbytes kilobytes.	 This limit is supported on all	operating sys-
	      tems which support the setrlimit(2) system  call.	  This	should
	      include most modern UNIX systems.

	      We  recommend  that you monitor your worker 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 to
	      consume lots of memory.

       -h     Print usage information and exit.

       -t filename
	      Log statistical information to filename.	See the	 section  STA-
	      TISTICS 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, mimede-
	      fang-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.

       -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 mimedefang-multiplexor.

       -q queue_size
	      Normally,	if all workers are busy	and mimedefang-multiplexor re-
	      ceives another request, it fails it  with	 the  error  "No  free
	      workers."	  However,  if	you  use  the  -q  option,  then up to
	      queue_size requests will be queued.  As soon as a	worker becomes
	      free,  the queued	requests will be handed	off in FIFO order.  If
	      the queue	is full	and another request comes in, then the request
	      is failed	with "No free workers".

       -Q queue_timeout
	      Queued requests should not stay on the queue indefinitely.  If a
	      queued request cannot be processed within	queue_timeout (default
	      30)  seconds  of	being placed on	the queue, it is failed	with a
	      "Queued request timed out" message.  See the  section  "QUEUEING
	      REQUESTS"	for more discussion.

       -O sock
	      Listen  on a notification	socket for connections from listeners.
	      mimedefang-multiplexor can inform	 external  programs  of	 state
	      changes by sending messages over a notification socket.  The ex-
	      ternal programs connect to this socket and then listen for noti-
	      fications.   See the section SOCKET SPECIFICATION	for the	format
	      of sock.

	      See the mimedefang-notify(7) man page for	details	of the notifi-
	      cation protocol.

       -N map_sock
	      Listen  on  a map	socket for Sendmail SOCKETMAP connections.  As
	      of Sendmail 8.13,	you can	define a Sendmail map type that	 talks
	      to  a  daemon  over a socket.  mimedefang-multiplexor implements
	      that protocol; consult the mimedefang-filter(5) man page for de-
	      tils (see	the SOCKET MAPS	section).

	      See the section SOCKET SPECIFICATION for the format of map_sock.

       -I backlog
	      When  mimedefang-multiplexor creates a listening socket, it cal-
	      culates the "backlog" argument to	listen(2) based	on the maximum
	      number of	workers.  However, you can explicitly set this backlog
	      with the -I option.  Setting the backlog to a high value (around
	      30-50) may help on a very	busy server.  If you see mail log mes-
	      sages saying "MXCommand: socket: Connection refused" during busy
	      periods,	then  that's  an  indication  you need a higher	listen

       -L interval
	      Log the worker status every interval seconds.  This logs a  line
	      using syslog; the	line looks like	this:

       Worker status: Stopped=s	Idle=i Busy=b Killed=k Queued=q	Msgs=m Activations=a

	      Here,  "Stopped" is the number of	non-running workers, "Idle" is
	      the number of idle workers, "Busy" is the	number of  busy	 work-
	      ers,  "Killed" is	the number of killed workers yet to be reaped,
	      "Queued" is the number of	queued requests, "Msgs"	is  the	 total
	      number  of  messages  processed since the	multiplexor began run-
	      ning, and	"Activations" is the number of times  a	 Perl  process
	      has been started since the multiplexor began running.

	      If  you supply an	interval of 0 (which is	the default), no peri-
	      odic status logging is performed.	 If you	supply an interval  of
	      less than	5 seconds, it is silently reset	to 5 seconds.

       -S facility
	      Specifies	 the syslog facility for log messages.	The default is
	      mail.  See openlog(3) for	a list of valid	facilities.   You  can
	      use either the short name	("mail") or long name ("LOG_MAIL") for
	      the facility name.

       -E     Specifies	that the multiplexor should create  an	embedded  Perl
	      interpreter.   This  can	improve	performance dramatically.  But
	      see the section "EMBEDDING PERL" for more	information.

       -X n   Specifies	that the multiplexor should initiate a "tick"  request
	      every  n seconds.	 This causes your filter_tick function (if de-
	      fined) to	be called.  Note that you have no control  over	 which
	      worker  executes	filter_tick.   If  all workers are busy	when a
	      tick occurs, that	tick request is	skipped	and a warning  message
	      is logged.

       -P n   Specifies	 that  the  multiplexor	 should	run n tick requests in
	      parallel.	 Each tick is run as often as specified	 with  the  -X
	      argument.	  (If you omit the -P option, then the multiplexor be-
	      haves as if -P 1 had been	specified.)

	      If you run parallel ticks, each  tick  is	 assigned  an  integer
	      identifying  its	"type".	 The type ranges from 0	to n-1.	 While
	      there may	be as many as n	tick requests running at a time,  only
	      one tick of each type will be active at any time.

       -Y label
	      Sets  the	tag used in the	multiplexor's syslog messages to label
	      instead of mimedefang-multiplexor.

       -G     Normally,	mimedefang-multiplexor uses a umask of 027 when	creat-
	      ing  listening  sockets.	 If  you  would	like the sockets to be
	      readable and writeable by	the group as well as the owner,	supply
	      the  -G  option.	This causes the	umask to be 007	whenever UNIX-
	      domain sockets are created.

       -y n   Limits the maximum number	of concurrent recipok checks to	n on a
	      per-domain  basis.   The	value  of n can	range from 0 (in which
	      case no limit is applied)	to maxWorkers, where maxWorkers	is the
	      argument	to  the	 -x option.  If	n is outside that range, it is
	      ignored (and no limit is applied.)

	      The recipok  command  ultimately	invokes	 the  filter_recipient
	      function	in  your filter.  If you are doing recipient verifica-
	      tion against servers that	may be slow or unreliable, you can use
	      the  -y option to	limit the number of concurrent recipient veri-
	      fications	per domain.  That way, if one domain's server  becomes
	      very  slow, it won't consume all available workers for recipient
	      verification.  Instead, its RCPT commands	will be	tempfailed and
	      there  will  be  workers	available  to handle RCPT commands for
	      other domains.

       The -a, -N and -O options take a	socket as an  argument.	  This	socket
       can be specified	as:

	      A	UNIX-domain socket

	      A	 TCP  socket  bound to port portnum, but which accepts connec-
	      tions only from the IPv4 loopback	address	(

	      A	TCP socket bound to port portnum which will accept connections
	      from any address.	 Use inet_any with caution!

	      A	 TCP  socket bound to port portnum listening on	the IPv6 loop-
	      back address.

	      A	TCP socket bound to port portnum listening on the  IPv6	 wild-
	      card address.

       Normally,  if  all workers are busy, any	additional requests are	failed
       immediately.  However, the -q and -Q options allow  you	to  queue  re-
       quests for a short amount of time.  This	facility is intended to	grace-
       fully handle a temporary	overload; most of the time, your queue	should
       be empty.

       Because	mimedefang checks the number of	free workers when a connection
       is opened and fails the connection if there are no  free	 workers,  the
       intent  of the queue is to allow	SMTP transactions that are already un-
       derway to continue if there is a	slight overload.  Any new  connections
       will  be	 failed	 if all	workers	are busy, but existing connections are
       allowed to continue.  Queuing requests may improve  throughput  on  ex-
       tremely busy servers.

       Note that if you	supply the -q option to	mimedefang, then even new con-
       nections	are allowed to queue.  This may	improve	throughput by  keeping
       the worker utilization higher.

       The  -R	option to mimedefang can be used to reserve a specified	number
       of workers for connections from the loopback address.  Using the	-R op-
       tion  has  the side-effect of permitting	new connections	from the loop-
       back address to queue.

       Normally, when mimedefang-multiplexor activates a worker, it forks  and
       execs  However, if the multiplexor was compiled with em-
       bedded Perl support, and	you supply the	-E  command-line  option,  the
       multiplexor works like this:

       1      It  creates  an  embedded	 Perl interpreter, and sources mimede- with a special command-line argument telling it to  read
	      the filter, but not to enter the main loop.

       2      Each  time  a  worker is activated, the multiplexor calls	fork()
	      and runs the main loop.  This invokes  filter_ini-
	      tialize and then runs the	main loop.

       On  some	platforms (for example,	Red Hat	Linux 7.3 with Perl 5.6.1), it
       is not safe to destroy and recreate a Perl interpreter without  causing
       a memory	leak.  On those	platforms, if you attempt to reread the	filter
       file (by	sending	the multiplexor	a HUP signal or	reread	command),  the
       filter will not be re-read, and a message will be logged	to syslog.  On
       those platforms,	you must kill and restart MIMEDefang if	you change the
       filter file.

       On most platforms, however, a filter reread is accomplished by destroy-
       ing and re-creating the embedded	interpreter, re-sourcing
       and killing workers as soon as they are idle.

       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 workers you run, ad-
       just 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:

	      A	worker process has been	started.

	      A	worker process has been	killed.

	      A	dead worker process has	been reaped.  It is possible to	have a
	      ReapWorker  event	 without  a  previous  KillWorker event	if the
	      worker process terminated	abnormally.

	      A	worker process has begun filtering an e-mail message.

	      A	worker process has finished filtering an e-mail	message.

       The possible keys in the	key=value pairs	are:

	      The worker involved in the event.	 Every worker is identified by
	      a	small integer.

	      The  total number	of running workers immediately after the event

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

	      The reason for a StartWorker or KillWorker event.	 (Present only
	      for these	events.)

	      The number of e-mails processed by the worker.  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 workers.   Also,  any  ac-
       tive-and-busy  workers  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 workers and exits immediately.

       mimedefang-mulitplexor was written  by  Dianne  Skoll  <dfs@roaringpen->.  The mimedefang home page is

SEE ALSO,  mimedefang-filter(5),	mimedefang(8), mimedefang-pro-

4th Berkeley Distribution	8 February 2005	     MIMEDEFANG-MULTIPLEXOR(8)


Want to link to this manual page? Use this URL:

home | help