Provided by: libsendmail-pmilter-perl_1.00-1.3_all bug

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

       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>

       •   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

perl v5.38.2                                       2024-03-17                             Sendmail::PMilter(3pm)