1Sendmail::PMilter(3)  User Contributed Perl Documentation Sendmail::PMilter(3)
2
3
4

NAME

6       Sendmail::PMilter - Perl binding of Sendmail Milter protocol
7

SYNOPSIS

9           use Sendmail::PMilter;
10
11           my $milter = new Sendmail::PMilter;
12
13           $milter->auto_setconn(NAME);
14           $milter->register(NAME, { CALLBACKS }, FLAGS);
15           $milter->main();
16

DESCRIPTION

18       Sendmail::PMilter is a mail filtering API implementing the Sendmail
19       milter protocol in pure Perl.  This allows Sendmail servers (and
20       perhaps other MTAs implementing milter) to filter and modify mail in
21       transit during the SMTP connection, all in Perl.
22
23       It should be noted that PMilter 0.90 and later is NOT compatible with
24       scripts written for PMilter 0.5 and earlier.  The API has been reworked
25       significantly, and the enhanced APIs and rule logic provided by PMilter
26       0.5 and earlier has been factored out for inclusion in a separate
27       package to be called Mail::Milter.
28

METHODS

30           get_max_interpreters()
31
32           Returns the maximum number of interpreters passed to "main()".
33           This is only useful when called from within the dispatcher, as it
34           is not set before "main()" is called.
35
36           get_max_requests()
37
38           Returns the maximum number of requests per interpreter passed to
39           "main()".  This is only useful when called from within the
40           dispatcher, as it is not set before "main()" is called.
41
42           main([MAXCHILDREN[, MAXREQ]])
43
44           This is the last method called in the main block of a milter
45           program.  If successful, this call never returns; the protocol
46           engine is launched and begins accepting connections.
47
48           MAXCHILDREN (default 0, meaning unlimited) specifies the maximum
49           number of connections that may be serviced simultaneously.  If a
50           connection arrives with the number of active connections above this
51           limit, the milter will immediately return a temporary failure
52           condition and close the connection.
53
54           MAXREQ (default 0, meaning unlimited) is the maximum number of
55           requests that a child may service before being recycled.  It is not
56           guaranteed that the interpreter will service this many requests,
57           only that it will not go over the limit.
58
59           Any callback which "die"s will have its output sent to "warn",
60           followed by a clean shutdown of the milter connection.  To catch
61           any warnings generated by the callbacks, and any error messages
62           caused by a "die", set $SIG{__WARN__} to a user-defined subroutine.
63           (See perlvar.)
64
65           register(NAME, CALLBACKS[, FLAGS])
66
67           Sets up the main milter loop configuration.
68
69           NAME is the name of the milter.  For compatibility with the
70           official Sendmail::Milter distribution, this should be the same
71           name as passed to auto_getconn() or auto_setconn(), but this
72           PMilter implementation does not enforce this.
73
74           CALLBACKS is a hash reference containing one or more callback
75           subroutines.  If a callback is not named in this hashref, the
76           caller's package will be searched for subroutines named
77           "CALLBACK_callback", where CALLBACK is the name of the callback
78           function.
79
80           FLAGS, if specified, is a bitmask of message modification actions
81           (a bitwise OR of the SMFIF_* constants, or SMFI_CURR_ACTS to ask
82           for all capabilities) that are requested by the callback object for
83           use during message processing.  If any bit is not set in this mask,
84           its corresponding action will not be allowed during message
85           processing.
86
87           "register()" must be called successfully exactly once.  If called a
88           second time, the previously registered callbacks will be erased.
89
90           Returns a true value on success, undef on failure.
91
92           setconn(DESC)
93
94           Sets up the server socket with connection descriptor DESC.  This is
95           identical to the descriptor syntax used by the "X" milter
96           configuration lines in sendmail.cf (if using Sendmail).  This
97           should be one of the following:
98
99           local:PATH
100             A local ("UNIX") socket on the filesystem, named PATH.  This has
101             some smarts that will auto-delete the pathname if it seems that
102             the milter is not currently running (but this currently contains
103             a race condition that may not be fixable; at worst, there could
104             be two milters running with one never receiving connections).
105
106           inet:PORT[@HOST]
107             An IPv4 socket, bound to address HOST (default INADDR_ANY), on
108             port PORT.  It is not recommended to open milter engines to the
109             world, so the @HOST part should be specified.
110
111           inet6:PORT[@HOST]
112             An IPv6 socket, bound to address HOST (default INADDR_ANY), on
113             port PORT.  This requires IPv6 support and the Perl INET6 package
114             to be installed.  It is not recommended to open milter engines to
115             the world, so the @HOST part should be specified.
116
117           Returns a true value on success, undef on failure.
118
119           set_dispatcher(CODEREF)
120
121           Sets the dispatcher used to accept socket connections and hand them
122           off to the protocol engine.  This allows pluggable resource
123           allocation so that the milter script may use fork, threads, or any
124           other such means of handling milter connections.  See "DISPATCHERS"
125           below for more information.
126
127           The subroutine (code) reference will be called by "main()" when the
128           listening socket object is prepared and ready to accept
129           connections.  It will be passed the arguments:
130
131               MILTER, LSOCKET, HANDLER
132
133           MILTER is the milter object currently running.  LSOCKET is a
134           listening socket (an instance of "IO::Socket"), upon which
135           "accept()" should be called.  HANDLER is a subroutine reference
136           which should be called, passing the socket object returned by
137           "LSOCKET->accept()".
138
139           Note that the dispatcher may also be set from one of the off-the-
140           shelf dispatchers noted in this document by setting the
141           PMILTER_DISPATCHER environment variable.  See "DISPATCHERS", below.
142
143           set_listen(BACKLOG)
144
145           Set the socket listen backlog to BACKLOG.  The default is 5
146           connections if not set explicitly by this method.  Only useful
147           before calling "main()".
148
149           set_socket(SOCKET)
150
151           Rather than calling "setconn()", this method may be called
152           explicitly to set the "IO::Socket" instance used to accept inbound
153           connections.
154

SENDMAIL-SPECIFIC METHODS

156       The following methods are only useful if Sendmail is the MTA connecting
157       to this milter.  Other MTAs likely don't use Sendmail's configuration
158       file, so these methods would not be useful with them.
159
160           auto_getconn(NAME[, CONFIG])
161
162           Returns the connection descriptor for milter NAME in Sendmail
163           configuration file CONFIG (default "/etc/mail/sendmail.cf" or
164           whatever was set by "set_sendmail_cf()").  This can then be passed
165           to setconn(), below.
166
167           Returns a true value on success, undef on failure.
168
169           auto_setconn(NAME[, CONFIG])
170
171           Creates the server connection socket for milter NAME in Sendmail
172           configuration file CONFIG.
173
174           Essentially, does:
175
176               $milter->setconn($milter->auto_getconn(NAME, CONFIG))
177
178           Returns a true value on success, undef on failure.
179
180           get_sendmail_cf()
181
182           Returns the pathname of the Sendmail configuration file set by
183           "set_sendmail_cf()", else the default of "/etc/mail/sendmail.cf".
184
185           get_sendmail_class(CLASS[, CONFIG])
186
187           Returns a list containing all members of the Sendmail class CLASS,
188           in Sendmail configuration file CONFIG (default
189           "/etc/mail/sendmail.cf" or whatever is set by "set_sendmail_cf()").
190           Typically this is used to look up the entries in class "w", the
191           local hostnames class.
192
193           set_sendmail_cf(FILENAME)
194
195           Set the default filename used by "auto_getconn", "auto_setconn",
196           and "sendmail_class" to find Sendmail-specific configuration data.
197           If not explicitly set by this method, it defaults to
198           "/etc/mail/sendmail.cf".
199

DISPATCHERS

201       Milter requests may be dispatched to the protocol handler in a
202       pluggable manner (see the description for the "set_dispatcher()" method
203       above).  "Sendmail::PMilter" offers some off-the-shelf dispatchers that
204       use different methods of resource allocation.
205
206       Each of these is referenced as a non-object function, and return a
207       value that may be passed directly to "set_dispatcher()".
208
209       Sendmail::PMilter::ithread_dispatcher()
210       (environment) PMILTER_DISPATCHER=ithread
211           The "ithread" dispatcher spins up a new thread upon each connection
212           to the milter socket.  This provides a thread-based model that may
213           be more resource efficient than the similar "postfork" dispatcher.
214           This requires that the Perl interpreter be compiled with
215           "-Duseithreads", and uses the "threads" module (available on Perl
216           5.8 or later only).
217
218       Sendmail::PMilter::prefork_dispatcher([PARAMS])
219       (environment) PMILTER_DISPATCHER=prefork
220           The "prefork" dispatcher forks the main Perl process before
221           accepting connections, and uses the main process to monitor the
222           children.  This should be appropriate for steady traffic flow
223           sites.  Note that if MAXINTERP is not set in the call to "main()"
224           or in PARAMS, an internal default of 10 processes will be used;
225           similarly, if MAXREQ is not set, 100 requests will be served per
226           child.
227
228           Currently the child process pool is fixed-size:  discarded children
229           will be immediately replaced.  This may change to use a dynamic
230           sizing method in the future, more like the Apache webserver's fork-
231           based model.
232
233           PARAMS, if specified, is a hash of key-value pairs defining
234           parameters for the dispatcher.  The available parameters that may
235           be set are:
236
237           child_init
238             subroutine reference that will be called after each child process
239             is forked.  It will be passed the "MILTER" object.
240
241           child_exit
242             subroutine reference that will be called just before each child
243             process terminates.  It will be passed the "MILTER" object.
244
245           max_children
246             Maximum number of child processes active at any time.  Equivalent
247             to the MAXINTERP option to main() -- if not set in the main()
248             call, this value will be used.
249
250           max_requests_per_child
251             Maximum number of requests a child process may service before
252             being recycled.  Equivalent to the MAXREQ option to main() -- if
253             not set in the main() call, this value will be used.
254
255       Sendmail::PMilter::postfork_dispatcher()
256       (environment) PMILTER_DISPATCHER=postfork
257           In this release, this is the default dispatcher for PMilter if no
258           explicit dispatcher is set.
259
260           The "postfork" dispatcher forks the main Perl process upon each
261           connection to the milter socket.  This is adequate for machines
262           that get bursty but otherwise mostly idle mail traffic, as the
263           idle-time resource consumption is very low.
264
265       Sendmail::PMilter::sequential_dispatcher()
266       (environment) PMILTER_DISPATCHER=sequential
267           The "sequential" dispatcher forces one request to be served at a
268           time, making other requests wait on the socket for the next pass
269           through the loop.  This is not suitable for most production
270           installations, but may be quite useful for milter debugging or
271           other software development purposes.
272
273           Note that, because the default socket backlog is 5 connections, it
274           may be wise to increase this backlog by calling "set_listen()"
275           before entering "main()" if using this dispatcher.
276

EXPORTS

278       Each of these symbols may be imported explicitly, imported with tag
279       ":all", or referenced as part of the "Sendmail::PMilter::" package.
280
281       Callback Return Values
282         Of these, SMFIS_CONTINUE will allow the milter to continue being
283         called for the remainder of the message phases.  All others will
284         terminate processing of the current message and take the noted
285         action.
286
287         As a special exception, SMFIS_REJECT and SMFIS_TEMPFAIL in the
288         "envrcpt" callback will reject only the current recipient, otherwise
289         continuing message processing as if SMFIS_CONTINUE were returned.
290
291           SMFIS_CONTINUE - continue processing the message
292           SMFIS_REJECT - reject the message with a 5xx error
293           SMFIS_DISCARD - accept, but discard the message
294           SMFIS_ACCEPT - accept the whole message as-is
295           SMFIS_TEMPFAIL - reject the message with a 4xx error
296
297       Milter Capability Request Flags
298         These values are bitmasks passed as the FLAGS argument to
299         "register()".  Some MTAs may choose different methods of resource
300         allocation, so keeping this list short may help the MTA's memory
301         usage.  If the needed capabilities are not known, however,
302         "SMFI_CURR_ACTS" should be used.
303
304           SMFIF_ADDHDRS - allow $ctx->addheader()
305           SMFIF_CHGBODY - allow $ctx->replacebody()
306           SMFIF_MODBODY - (compatibility synonym for SMFIF_CHGBODY)
307           SMFIF_ADDRCPT - allow $ctx->addrcpt()
308           SMFIF_DELRCPT - allow $ctx->delrcpt()
309           SMFIF_CHGHDRS - allow $ctx->chgheader()
310
311           SMFIF_QUARANTINE - allow $ctx->quarantine()
312             (requires Sendmail 8.13; not defined in Sendmail::Milter)
313
314           SMFIF_SETSENDER - allow $ctx->setsender()
315             (requires special Sendmail patch; see below[*])
316
317           SMFI_V1_ACTS - SMFIF_ADDHDRS through SMFIF_DELRCPT
318             (Sendmail 8.11 _FFR_MILTER capabilities)
319
320           SMFI_V2_ACTS - SMFIF_ADDHDRS through SMFIF_CHGHDRS
321           SMFI_CURR_ACTS - (compatibility synonym for SMFI_V2_ACTS)
322             (Sendmail 8.12 capabilities)
323
324           (Currently no combined macro includes SMFIF_QUARANTINE or
325           SMFIF_SETSENDER.)
326
327         [*] NOTE: SMFIF_SETSENDER is not official as of Sendmail 8.13.x. To
328         enable this flag, Sendmail must be patched with the diff available
329         from:
330
331           C<http://www.sourceforge.net/projects/mlfi-setsender>
332
333         Additionally, the following statement must appear after the "use"
334         statements in your milter program; otherwise, setsender() will always
335         fail when called:
336
337           local $Sendmail::PMilter::enable_setsender = 1;
338

SECURITY CONSIDERATIONS

340       Running as root
341           Running Perl as root is dangerous.  Running "Sendmail::PMilter" as
342           root may well be system-assisted suicide at this point.  So don't
343           do that.
344
345           More specifically, though, it is possible to run a milter frontend
346           as root, in order to gain access to network resources (such as a
347           filesystem socket in /var/run), and then drop privileges before
348           accepting connections.  To do this, insert drop-privileges code
349           between calls to setconn/auto_setconn and main; for instance:
350
351               $milter->auto_setconn('pmilter');
352               $> = 65534; # drop root privileges
353               $milter->main();
354
355           The semantics of properly dropping system administrator privileges
356           in Perl are, unfortunately, somewhat OS-specific, so this process
357           is not described in detail here.
358

AUTHOR

360       Todd Vierling, <tv@duh.org> <tv@pobox.com>
361

Maintenance

363       Since 0.96 Sendmail::Pmilter is no longer maintained on
364       sourceforge.net, cpan:AVAR took it over in version 0.96 to fix a minor
365       bug and currently owns the module in PAUSE.
366
367       However this module is effectively orphaned and looking for a new
368       maintainer. The current maintainer doesn't use Sendmail and probably
369       never will again. If this code is important to you and you find a bug
370       in it or want something new implemented please:
371
372       ·   Fork it & fix it on GitHub at
373           http://github.com/avar/sendmail-pmilter
374           <http://github.com/avar/sendmail-pmilter>
375
376       ·   Send AVAR an E-Mail requesting upload permissions so you can upload
377           the fixed version to the CPAN.
378

SEE ALSO

380       Sendmail::PMilter::Context for a description of the arguments passed to
381       each callback function
382
383       The project homepage:  http://pmilter.sourceforge.net/
384

THANKS

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

POD ERRORS

389       Hey! The above document had some coding errors, which are explained
390       below:
391
392       Around line 83:
393           You can't have =items (as at line 127) unless the first thing after
394           the =over is an =item
395
396       Around line 471:
397           You can't have =items (as at line 477) unless the first thing after
398           the =over is an =item
399
400       Around line 979:
401           You forgot a '=back' before '=head1'
402
403       Around line 1045:
404           =back without =over
405
406
407
408perl v5.12.0                      2010-03-12              Sendmail::PMilter(3)
Impressum