view release on metacpan or  search on metacpan

mimedefang-multiplexor.8.in  view on Meta::CPAN

See the \fBmimedefang-notify\fR(7) man page for details of the notification
protocol.

.TP
.B \-N \fImap_sock\fR
Listen on a \fImap socket\fR for Sendmail SOCKETMAP connections.
As of Sendmail 8.13, you can define a Sendmail map type that talks
to a daemon over a socket.  \fBmimedefang-multiplexor\fR implements
that protocol; consult the \fBmimedefang-filter\fR(5) man page
for detils (see the SOCKET MAPS section).

See the section SOCKET SPECIFICATION for the format of \fImap_sock\fR.



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

.TP
.B \-L \fIinterval\fR
Log the worker status every \fIinterval\fR seconds.  This logs a line using
syslog; the line looks like this:

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

Here, "Stopped" is the number of non-running workers, "Idle" is the
number of idle workers, "Busy" is the number of busy workers, "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 running, and "Activations" is
the number of times a Perl process has been started since the
multiplexor began running.

If you supply an \fIinterval\fR of 0 (which is the default), no periodic
status logging is performed.  If you supply an \fIinterval\fR of less than
5 seconds, it is silently reset to 5 seconds.

.TP
\fB\-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
\fB\-E\fR
Specifies that the multiplexor should create an embedded Perl interpreter.
This can improve performance dramatically.  But see the section
"EMBEDDING PERL" for more information.

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

.TP
\fB\-P\fR \fIn\fR
Specifies that the multiplexor should run \fIn\fR tick requests in
parallel.  Each tick is run as often as specified with the
\fB\-X\fR argument.  (If you omit the \fB\-P\fR option, then the
multiplexor behaves as if \fB\-P 1\fR had been specified.)

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

.TP
\fB\-Y\fR \fIlabel\fR
Sets the tag used in the multiplexor's syslog messages to
\fIlabel\fR instead of \fBmimedefang-multiplexor\fR.

.TP
\fB\-k\fR
Enable adaptive autoscaling of the worker pool.  When this option is
supplied, \fBmimedefang-multiplexor\fR periodically computes an
exponential moving average (EMA) of the busy-worker ratio and
automatically starts or stops workers to match demand:

.RS
.PP
If the EMA busy ratio exceeds 80%, an additional worker is activated
(up to \fImaxWorkers\fR, as set by \fB\-x\fR).

.PP
If the EMA busy ratio falls below 30%, an excess worker is killed
(down to \fIminWorkers\fR, as set by \fB\-m\fR).
.RE

.PP
The check is performed every 15 seconds.  To avoid thrashing, a
scale-out event cannot occur within 5 seconds of the previous
scale-out, and a scale-in event cannot occur within 30 seconds of the
previous scale-out or scale-in.

.PP
The current autoscaling state (enabled flag, EMA value, and all
thresholds) can be inspected at any time with the \fBautoscale\fR
command via \fBmd-mx-ctrl\fR(8).

.TP
\fB\-G\fR
Normally, \fBmimedefang-multiplexor\fR uses a umask of 027 when
creating listening sockets.  If you would like the sockets to be
readable and writeable by the group as well as the owner,
supply the \fB\-G\fR option.  This causes the umask to be 007

mimedefang-multiplexor.8.in  view on Meta::CPAN

RCPT commands will be tempfailed and there will be workers available
to handle RCPT commands for other domains.
.RE

.SH SOCKET SPECIFICATION

The \fB\-a\fR, \fB\-N\fR and \fB\-O\fR options takes a socket as an
argument.
The format of the socket parameter is similar to that of the Sendmail Milter library,
and is one of the following:

.TP
.B /path/to/socket
A UNIX-domain socket

.TP
.B inet:portnum
A TCP socket bound to port \fIportnum\fR, but which accepts connections
only from the IPv4 loopback address (127.0.0.1).

.TP
.B inet_any:portnum
A TCP socket bound to port \fIportnum\fR which will accept connections
from any address.  \fIUse inet_any with caution!\fR

.TP
.B inet6:portnum
A TCP socket bound to port \fIportnum\fR listening on the IPv6 loopback
address.

.TP
.B inet6_any:portnum
A TCP socket bound to port \fIportnum\fR listening on the IPv6 wildcard
address.

.SH QUEUEING REQUESTS

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

Because \fBmimedefang\fR 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 underway 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 extremely busy servers.

Note that if you supply the \fB\-q\fR option to \fBmimedefang\fR, then
even new connections are allowed to queue.  This may improve throughput by
keeping the worker utilization higher.

The \fB\-R\fR option to \fBmimedefang\fR can be used to reserve a
specified number of workers for connections from the loopback address.  Using
the \fB\-R\fR option has the side-effect of permitting new connections
from the loopback address to queue.

.SH EMBEDDING PERL

Normally, when \fBmimedefang-multiplexor\fR activates a worker, it forks
and execs \fBmimedefang.pl\fR.  However, if the multiplexor was compiled
with embedded Perl support, and you supply the \fB\-E\fR command-line
option, the multiplexor works like this:

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

.TP
2
Each time a worker is activated, the multiplexor calls fork() and runs the
\fBmimedefang.pl\fR main loop.  This invokes \fBfilter_initialize\fR
and then runs the main loop.

.PP
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 \fInot\fR 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.

.PP
On most platforms, however, a filter reread is accomplished by destroying
and re-creating the embedded interpreter, re-sourcing \fBmimedefang.pl\fR
and killing workers as soon as they are idle.

.SH STATISTICS
With the \fB\-t\fR option, \fBmimedefang-multiplexor\fR 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, adjust timeouts, and so on.

.PP
Each line of the file looks like this:

.nf
	YYYY/MM/DD:HH:MM:SS timestamp event key=val key=val...
.fi

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:

.TP
.B StartWorker
A worker process has been started.

.TP
.B KillWorker
A worker process has been killed.

.TP
.B ReapWorker
A dead worker process has been reaped.  It is possible to have a ReapWorker