Ubuntu Manpage: Sendmail::PMilter - Perl binding of Sendmail Milter protocol

Provided by: libsendmail-pmilter-perl_1.00-1_all

NAME

       Sendmail::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();

DESCRIPTION

       Sendmail::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.

METHODS

get_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.)

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>

       •   Send AVAR an E-Mail requesting upload permissions so you can upload the fixed version
           to the CPAN.

THANKS

       rob.casey@bluebottle.com - for the prefork mechanism idea