Sendmail::PMilter(3) User Contributed Perl Documentation Sendmail::PMilter(3)NAMESendmail::PMilter - Perl binding of Sendmail Milter protocol
SYNOPSIS
use Sendmail::PMilter;
my $milter = new Sendmail::PMilter;
$milter->auto_setconn(NAME);
$milter->register(NAME, { CALLBACKS }, FLAGS);
$milter->main();
DESCRIPTIONSendmail::PMilter is a mail filtering API implementing the Sendmail
milter protocol in pure Perl. This allows Sendmail servers (and
perhaps other MTAs implementing milter) to filter and modify mail in
transit during the SMTP connection, all in Perl.
It should be noted that PMilter 0.90 and later is NOT compatible with
scripts written for PMilter 0.5 and earlier. The API has been reworked
significantly, and the enhanced APIs and rule logic provided by PMilter
0.5 and earlier has been factored out for inclusion in a separate
package to be called Mail::Milter.
METHODSget_max_interpreters()
Returns the maximum number of interpreters passed to "main()".
This is only useful when called from within the dispatcher, as it
is not set before "main()" is called.
get_max_requests()
Returns the maximum number of requests per interpreter passed to
"main()". This is only useful when called from within the
dispatcher, as it is not set before "main()" is called.
main([MAXCHILDREN[, MAXREQ]])
This is the last method called in the main block of a milter
program. If successful, this call never returns; the protocol
engine is launched and begins accepting connections.
MAXCHILDREN (default 0, meaning unlimited) specifies the maximum
number of connections that may be serviced simultaneously. If a
connection arrives with the number of active connections above this
limit, the milter will immediately return a temporary failure
condition and close the connection.
MAXREQ (default 0, meaning unlimited) is the maximum number of
requests that a child may service before being recycled. It is not
guaranteed that the interpreter will service this many requests,
only that it will not go over the limit.
Any callback which "die"s will have its output sent to "warn",
followed by a clean shutdown of the milter connection. To catch
any warnings generated by the callbacks, and any error messages
caused by a "die", set $SIG{__WARN__} to a user-defined subroutine.
(See perlvar.)
register(NAME, CALLBACKS[, FLAGS])
Sets up the main milter loop configuration.
NAME is the name of the milter. For compatibility with the
official Sendmail::Milter distribution, this should be the same
name as passed to auto_getconn() or auto_setconn(), but this
PMilter implementation does not enforce this.
CALLBACKS is a hash reference containing one or more callback
subroutines. If a callback is not named in this hashref, the
caller's package will be searched for subroutines named
"CALLBACK_callback", where CALLBACK is the name of the callback
function.
FLAGS, if specified, is a bitmask of message modification actions
(a bitwise OR of the SMFIF_* constants, or SMFI_CURR_ACTS to ask
for all capabilities) that are requested by the callback object for
use during message processing. If any bit is not set in this mask,
its corresponding action will not be allowed during message
processing.
"register()" must be called successfully exactly once. If called a
second time, the previously registered callbacks will be erased.
Returns a true value on success, undef on failure.
setconn(DESC)
Sets up the server socket with connection descriptor DESC. This is
identical to the descriptor syntax used by the "X" milter
configuration lines in sendmail.cf (if using Sendmail). This
should be one of the following:
local:PATH
A local ("UNIX") socket on the filesystem, named PATH. This has
some smarts that will auto-delete the pathname if it seems that
the milter is not currently running (but this currently contains
a race condition that may not be fixable; at worst, there could
be two milters running with one never receiving connections).
inet:PORT[@HOST]
An IPv4 socket, bound to address HOST (default INADDR_ANY), on
port PORT. It is not recommended to open milter engines to the
world, so the @HOST part should be specified.
inet6:PORT[@HOST]
An IPv6 socket, bound to address HOST (default INADDR_ANY), on
port PORT. This requires IPv6 support and the Perl INET6 package
to be installed. It is not recommended to open milter engines to
the world, so the @HOST part should be specified.
Returns a true value on success, undef on failure.
set_dispatcher(CODEREF)
Sets the dispatcher used to accept socket connections and hand them
off to the protocol engine. This allows pluggable resource
allocation so that the milter script may use fork, threads, or any
other such means of handling milter connections. See "DISPATCHERS"
below for more information.
The subroutine (code) reference will be called by "main()" when the
listening socket object is prepared and ready to accept
connections. It will be passed the arguments:
MILTER, LSOCKET, HANDLER
MILTER is the milter object currently running. LSOCKET is a
listening socket (an instance of "IO::Socket"), upon which
"accept()" should be called. HANDLER is a subroutine reference
which should be called, passing the socket object returned by
"LSOCKET->accept()".
Note that the dispatcher may also be set from one of the off-the-
shelf dispatchers noted in this document by setting the
PMILTER_DISPATCHER environment variable. See "DISPATCHERS", below.
set_listen(BACKLOG)
Set the socket listen backlog to BACKLOG. The default is 5
connections if not set explicitly by this method. Only useful
before calling "main()".
set_socket(SOCKET)
Rather than calling "setconn()", this method may be called
explicitly to set the "IO::Socket" instance used to accept inbound
connections.
SENDMAIL-SPECIFIC METHODS
The following methods are only useful if Sendmail is the MTA connecting
to this milter. Other MTAs likely don't use Sendmail's configuration
file, so these methods would not be useful with them.
auto_getconn(NAME[, CONFIG])
Returns the connection descriptor for milter NAME in Sendmail
configuration file CONFIG (default "/etc/mail/sendmail.cf" or
whatever was set by "set_sendmail_cf()"). This can then be passed
to setconn(), below.
Returns a true value on success, undef on failure.
auto_setconn(NAME[, CONFIG])
Creates the server connection socket for milter NAME in Sendmail
configuration file CONFIG.
Essentially, does:
$milter->setconn($milter->auto_getconn(NAME, CONFIG))
Returns a true value on success, undef on failure.
get_sendmail_cf()
Returns the pathname of the Sendmail configuration file set by
"set_sendmail_cf()", else the default of "/etc/mail/sendmail.cf".
get_sendmail_class(CLASS[, CONFIG])
Returns a list containing all members of the Sendmail class CLASS,
in Sendmail configuration file CONFIG (default
"/etc/mail/sendmail.cf" or whatever is set by "set_sendmail_cf()").
Typically this is used to look up the entries in class "w", the
local hostnames class.
set_sendmail_cf(FILENAME)
Set the default filename used by "auto_getconn", "auto_setconn",
and "sendmail_class" to find Sendmail-specific configuration data.
If not explicitly set by this method, it defaults to
"/etc/mail/sendmail.cf".
DISPATCHERS
Milter requests may be dispatched to the protocol handler in a
pluggable manner (see the description for the "set_dispatcher()" method
above). "Sendmail::PMilter" offers some off-the-shelf dispatchers that
use different methods of resource allocation.
Each of these is referenced as a non-object function, and return a
value that may be passed directly to "set_dispatcher()".
Sendmail::PMilter::ithread_dispatcher()
(environment) PMILTER_DISPATCHER=ithread
The "ithread" dispatcher spins up a new thread upon each connection
to the milter socket. This provides a thread-based model that may
be more resource efficient than the similar "postfork" dispatcher.
This requires that the Perl interpreter be compiled with
"-Duseithreads", and uses the "threads" module (available on Perl
5.8 or later only).
Sendmail::PMilter::prefork_dispatcher([PARAMS])
(environment) PMILTER_DISPATCHER=prefork
The "prefork" dispatcher forks the main Perl process before
accepting connections, and uses the main process to monitor the
children. This should be appropriate for steady traffic flow
sites. Note that if MAXINTERP is not set in the call to "main()"
or in PARAMS, an internal default of 10 processes will be used;
similarly, if MAXREQ is not set, 100 requests will be served per
child.
Currently the child process pool is fixed-size: discarded children
will be immediately replaced. This may change to use a dynamic
sizing method in the future, more like the Apache webserver's fork-
based model.
PARAMS, if specified, is a hash of key-value pairs defining
parameters for the dispatcher. The available parameters that may
be set are:
child_init
subroutine reference that will be called after each child process
is forked. It will be passed the "MILTER" object.
child_exit
subroutine reference that will be called just before each child
process terminates. It will be passed the "MILTER" object.
max_children
Maximum number of child processes active at any time. Equivalent
to the MAXINTERP option to main()-- if not set in the main()
call, this value will be used.
max_requests_per_child
Maximum number of requests a child process may service before
being recycled. Equivalent to the MAXREQ option to main()-- if
not set in the main() call, this value will be used.
Sendmail::PMilter::postfork_dispatcher()
(environment) PMILTER_DISPATCHER=postfork
In this release, this is the default dispatcher for PMilter if no
explicit dispatcher is set.
The "postfork" dispatcher forks the main Perl process upon each
connection to the milter socket. This is adequate for machines
that get bursty but otherwise mostly idle mail traffic, as the
idle-time resource consumption is very low.
Sendmail::PMilter::sequential_dispatcher()
(environment) PMILTER_DISPATCHER=sequential
The "sequential" dispatcher forces one request to be served at a
time, making other requests wait on the socket for the next pass
through the loop. This is not suitable for most production
installations, but may be quite useful for milter debugging or
other software development purposes.
Note that, because the default socket backlog is 5 connections, it
may be wise to increase this backlog by calling "set_listen()"
before entering "main()" if using this dispatcher.
EXPORTS
Each of these symbols may be imported explicitly, imported with tag
":all", or referenced as part of the "Sendmail::PMilter::" package.
Callback Return Values
Of these, SMFIS_CONTINUE will allow the milter to continue being
called for the remainder of the message phases. All others will
terminate processing of the current message and take the noted
action.
As a special exception, SMFIS_REJECT and SMFIS_TEMPFAIL in the
"envrcpt" callback will reject only the current recipient, otherwise
continuing message processing as if SMFIS_CONTINUE were returned.
SMFIS_CONTINUE - continue processing the message
SMFIS_REJECT - reject the message with a 5xx error
SMFIS_DISCARD - accept, but discard the message
SMFIS_ACCEPT - accept the whole message as-is
SMFIS_TEMPFAIL - reject the message with a 4xx error
Milter Capability Request Flags
These values are bitmasks passed as the FLAGS argument to
"register()". Some MTAs may choose different methods of resource
allocation, so keeping this list short may help the MTA's memory
usage. If the needed capabilities are not known, however,
"SMFI_CURR_ACTS" should be used.
SMFIF_ADDHDRS - allow $ctx->addheader()
SMFIF_CHGBODY - allow $ctx->replacebody()
SMFIF_MODBODY - (compatibility synonym for SMFIF_CHGBODY)
SMFIF_ADDRCPT - allow $ctx->addrcpt()
SMFIF_DELRCPT - allow $ctx->delrcpt()
SMFIF_CHGHDRS - allow $ctx->chgheader()
SMFIF_QUARANTINE - allow $ctx->quarantine()
(requires Sendmail 8.13; not defined in Sendmail::Milter)
SMFIF_SETSENDER - allow $ctx->setsender()
(requires special Sendmail patch; see below[*])
SMFI_V1_ACTS - SMFIF_ADDHDRS through SMFIF_DELRCPT
(Sendmail 8.11 _FFR_MILTER capabilities)
SMFI_V2_ACTS - SMFIF_ADDHDRS through SMFIF_CHGHDRS
SMFI_CURR_ACTS - (compatibility synonym for SMFI_V2_ACTS)
(Sendmail 8.12 capabilities)
(Currently no combined macro includes SMFIF_QUARANTINE or
SMFIF_SETSENDER.)
[*] NOTE: SMFIF_SETSENDER is not official as of Sendmail 8.13.x. To
enable this flag, Sendmail must be patched with the diff available
from:
C<http://www.sourceforge.net/projects/mlfi-setsender>
Additionally, the following statement must appear after the "use"
statements in your milter program; otherwise, setsender() will always
fail when called:
local $Sendmail::PMilter::enable_setsender = 1;
SECURITY CONSIDERATIONS
Running as root
Running Perl as root is dangerous. Running "Sendmail::PMilter" as
root may well be system-assisted suicide at this point. So don't
do that.
More specifically, though, it is possible to run a milter frontend
as root, in order to gain access to network resources (such as a
filesystem socket in /var/run), and then drop privileges before
accepting connections. To do this, insert drop-privileges code
between calls to setconn/auto_setconn and main; for instance:
$milter->auto_setconn('pmilter');
$> = 65534; # drop root privileges
$milter->main();
The semantics of properly dropping system administrator privileges
in Perl are, unfortunately, somewhat OS-specific, so this process
is not described in detail here.
AUTHOR
Todd Vierling, <tv@duh.org> <tv@pobox.com>
Maintenance
Since 0.96 Sendmail::Pmilter is no longer maintained on
sourceforge.net, cpan:AVAR took it over in version 0.96 to fix a minor
bug and currently owns the module in PAUSE.
However this module is effectively orphaned and looking for a new
maintainer. The current maintainer doesn't use Sendmail and probably
never will again. If this code is important to you and you find a bug
in it or want something new implemented please:
· Fork it & fix it on GitHub at
http://github.com/avar/sendmail-pmilter
<http://github.com/avar/sendmail-pmilter>
· Send AVAR an E-Mail requesting upload permissions so you can upload
the fixed version to the CPAN.
SEE ALSO
Sendmail::PMilter::Context for a description of the arguments passed to
each callback function
The project homepage: http://pmilter.sourceforge.net/
THANKS
rob.casey@bluebottle.com - for the prefork mechanism idea
POD ERRORS
Hey! The above document had some coding errors, which are explained
below:
Around line 83:
You can't have =items (as at line 127) unless the first thing after
the =over is an =item
Around line 471:
You can't have =items (as at line 477) unless the first thing after
the =over is an =item
Around line 979:
You forgot a '=back' before '=head1'
Around line 1045:
=back without =over
perl v5.14.0 2011-04-16 Sendmail::PMilter(3)
