pmx1 - Run a PureMessage mail filter
pmx1 [-b] [-D] [-d N] [-f] [-L file] [-l N] [-i M:N] [-n N] [-p port] [-q M:N] [-r N] [-s PORT] [-T N] [-t N] [-u user[:group]] [-v] [-Z] [-z] Filter::Name [-- args]
pmx1 -h
The pmx1
program is deprecated. Consider setting up the milters to run
in the pmx.conf file and use the new pmx
command to start, stop
and monitor them.
As an example, instead of starting a milter with
pmx1 -p local:/tmp/pmx.sock Filter::Name
you would add this section
<milter Filter::Name> port = local:/tmp/pmx.sock </milter>
to the pmx.conf file and the start it up with pmx start
and shut
it down with pmx stop
.
The correspondence between pmx1 options and pmx.conf directives are as follows. See ``man pmx.conf'' for more information on the directives.
concurrency_limit_action = wait
debug_level
use_threads = no
pooled_proc_idle_limit
pooled_proc_connect_limit
stdin
and stdout
.
listen_queue_size
reinit_limit
port
smtp_listen_port
min_pooled_procs
max_pooled_procs
thread_stack_size
concurrency_limit
smtp_talk_port
timeout
user
message_log
log_utc
max_proto_data_size
pmx1
is the PureMessage v1.x driver program for mail filters. It is used
to start a milter process that sendmail will communicate with at a
specified port for filtering messages.
PureMessage filters are simple Perl modules that must be written in a particular way. The interface they must conform to in order to be usable as sendmail filters is described in PerlMx.
PureMessage filters are executed in a multi-threaded environment by creating independent Perl interpreters for every incoming filter request and executing the callbacks defined by the filter module in these interpreters.
The specified Filter::Name
is loaded via perl's -M
switch,
i.e., by running perl -MFilter::Name -e0
. Thus, additional
imports may be passed using the syntax allowed by perl's -M
switch. For example:
pmx MyFilter=a,b,c
causes the filter to be loaded via
use MyFilter qw(a b c);
Any additional options after a --
are passed through to the perl
interpreters. A double --
is needed to force arguments to be
visible in @ARGV
for the filter.
pmx1
provides several options to control the characteristics of a
PureMessage filter process. These are described below.
The following options are recognized by the pmx1
program:
This option is currently meaningless when the process pool is enabled.
See the -q
switch for the behavior in that case.
Use the -r
switch to increase the number of available interpreters.
This option is not relevant to the normal operation of PureMessage filters. Any internal warnings and error messages while processing filters are always logged via the system's native logging facility, such as syslog(3), irrespective of whether this flag was specified or not.
Note that PureMessage filters can choose to implement their own particular
error logging mechanism, perhaps via printing to the STDERR handle or using
the standard Sys::Syslog
module.
-r
switch is not honored by this option.
If you find that PureMessage is unstable under high or sustained load, this option should be enabled.
This option should also be enabled when running custom filters which use code or libraries that are not known to be thread safe.
NOTE: This option is obsolete, and is only supported for backward
compatibility. Use the -q
switch instead for better performance
and robustness.
-q
switch is not specified.
The seconds figure is the amount of ``idle'' time beyond which processes in the pool may be retired.
The requests figure is the number of connections that each process in the pool can handle. The process will be retired once this many connections have been serviced by it.
Note that pmx1
maintains a minimum number of processes in the pool
subject to the -q
switch. The seconds figure therefore only
applies to processes that exceed this minimum. The requests figure
applies to all processes, but pmx1
will start new processes as
necessary to maintain the minimum.
file
, which can be
a literal file name or a pattern that has embedded %
characters.
In the latter case, stdout and stderr will be redirected to separate
files, the names of which are obtained by replacing any %
characters in file
with ``out'' and ``err'', respectively.
-Z
switch selects the time format for the log entries.
INPUT_MAIL_FILTER()
macro in the .mc file or by using the X
key
letter in sendmail.cf. See the sendmail documentation for details.
The sendmail process need not be on the same host as the filter process.
port is a complete port specification that describes either a unix domain socket, an inet port or an IPv6 inet port. These three types of ports are specified as in the following examples:
local:/var/run/f1.sock inet:12345 inet:12345@foo.bar.org inet6:999@localhost
The first example waits for connections on a unix domain socket at
/var/run/f1.sock. The second example accepts connections on port 12345
(on any network interface). The third example is similar to the second,
but only accepts connections on the interface corresponding to
foo.bar.org
, if there is more than one network interface. The fourth
example accepts connections only on the loopback interface (::1
)
of an IPv6 port.
If not specified, the port defaults to inet:3366@localhost
.
If no port type prefix is specified it defaults to local:
. This
means that pmx -p 999 ...
will create a named socked called
999 in the current directory.
pmx1
will always maintain at least min processes in the pool.
Depending on the prevailing demand for connections, additional
processes will be started, up to a grand total of max processes
in the pool. Each such additional process will be automatically shut
down if it is detected to be idle for more than the time limit
specified by the -i switch.
pmx1
distributes incoming connections among the processes in
the pool, up to the concurrency limit for each process (see the
-r
switch). If all available capacity is exhausted, pmx1
will stop listening for incoming connections until enough
capacity is freed up by the completion of pending requests.
-f
switch is specified,
i.e., requests are handled by forking a separate process for each
request.
Setting a higher value may mean higher memory consumption. New interpreters are only created if all existing interpreters are executing other filter requests. Once created, interpreters are maintained in a pool to service requests, and are not normally deallocated until the filter process shuts down.
This option works whether or not the process pool is enabled via the
-q
switch. When the process pool is enabled, the -r
switch
specifies the concurrency of each process in the process pool. This
means that the total number of requests that can be satisfied
concurrently will be the product of the number of processes in the
process pool and the value of the -r
switch.
The optimum number of interpreters is usually a function of how fast
requests come in, the size of the process pool (if enabled via the
-q
switch), and how fast each filter can process requests.
If not specified, number defaults to 50 on platforms with mature threads support. Otherwise, the default is 1.
pmx1
to be more verbose about what it is doing. This currently
includes version numbers and license information.
-M
switch.
Sets the limit (in bytes) for the size of data used in protocol operations. Among other things, the limit applies to the total size of header data allowed in messages. The default value is 65535.
This limit can only be changed to a value that the connecting MTA will be capable of supporting.
the pmx manpage, the pmx.conf manpage, PerlMx
Copyright (C) 2000-2005 Sophos Group. All rights reserved. Sophos and PureMessage are trademarks of Sophos Plc and Sophos Group.