NAME

pmx1 - Run a PureMessage mail filter


SYNOPSIS

    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


NOTE

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.

-b
concurrency_limit_action = wait

-d
debug_level

-f
use_threads = no

-i
pooled_proc_idle_limit

pooled_proc_connect_limit

-L
stdin and stdout.

-l
listen_queue_size

-n
reinit_limit

-p
port

smtp_listen_port

-q
min_pooled_procs

max_pooled_procs

-T
thread_stack_size

-r
concurrency_limit

-s
smtp_talk_port

-t
timeout

-u
user

-M
message_log

-Z
log_utc

-z
max_proto_data_size


DESCRIPTION

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.


OPTIONS

The following options are recognized by the pmx1 program:

-b
Determines the behavior when there are more incoming filter requests than there are available interpreters to service those requests. If this switch is used, and when there are no more available interpreters, PureMessage will block waiting for an interpreter to become available. The normal behavior is to send a ``temporary failure'' code back to sendmail.

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.

-D
Runs pmx as a daemon. This means that the pmx process will put itself in the background and detach itself from the controlling terminal. This also means pmx will continue to run even if the shell or other parent process from which it was launched goes away. All output that normally goes to stdout or stderr is lost unless such output has been redirected using the -L switch.

-d number
Sets the debug level of PureMessage. This is generally only useful for debugging the inner workings of the sendmail Milter library.

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.

-f
Handle connections by forking multiple processes instead of running multiple threads. This option is useful on platforms that have immature, inefficient, or buggy threading implementations. (Linux and FreeBSD fall under that category as of early 2002.) The -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.

-h
Prints out a brief help message.

-i seconds:requests
Determines the limits that each process in the process pool is subject to. This option has no effect if the -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.

-L file
Redirects stdout and stderr to the specified 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.

-l number
Sets the size of the socket listen queue, which controls the maximum number of pending connections beyond which connections will be refused. Some operating systems may not honor the value specified. The default is 0, which means that the system default is used.

-M file
Enable the message log and have log entries go to the specified file. The -Z switch selects the time format for the log entries.

-n number
Sets the number of times an interpreter will be used to handle connections before it is discarded and reinitialized. Setting it to a value of 0 will force interpreters to never be discarded, which is only safe to do if you are absolutely certain that there are no memory leaks, either in your system libraries or in any of the filters. Default is 2048.

-p port
Specifies the port to listen to incoming requests from sendmail. Note that a version of sendmail that supports mail filters (v8.11.0 and later do) should be independently configured to send filter requests to the port. This is typically done using the 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.

-q max:min
Enables the pre-forked process pool, and sets the maximum and minimum number of processes allowed in it.

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.

-T number
This specifies how much stack space (in KB) to allocate to the milter threads. If not specified, defaults to 1024. A value of 0 forces the system default value to be used.

-r number
Sets the level of concurrency within each PureMessage process for handling requests. This limits the maximum number of Perl interpreters that will be created within each process to service incoming filter requests. This option is ignored when the -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.

See also the -b and -q switches.

-t timeout
Sets the number of seconds to wait for reads and writes on the port specified by the -p option. This should normally not be changed.

-u user[:group]
Sets the user and optionally the group that the filter should run as. Both names and the numeric ids are accepted.

-v
Enables pmx1 to be more verbose about what it is doing. This currently includes version numbers and license information.

-Z
Use UTC timestamps for the message log if enabled with the -M switch.

-z max_proto_data_size
This is a low-level option that is not meant to be used without advanced knowledge of PureMessage internals.

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.


SEE ALSO

the pmx manpage, the pmx.conf manpage, PerlMx


COPYRIGHT

Copyright (C) 2000-2005 Sophos Group. All rights reserved. Sophos and PureMessage are trademarks of Sophos Plc and Sophos Group.