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           If the maximum number of interpreters is running when a new
266           connection comes in, this dispatcher blocks until a slot becomes
267           available for a new interpreter.
268
269       Sendmail::PMilter::sequential_dispatcher()
270       (environment) PMILTER_DISPATCHER=sequential
271           The "sequential" dispatcher forces one request to be served at a
272           time, making other requests wait on the socket for the next pass
273           through the loop.  This is not suitable for most production
274           installations, but may be quite useful for milter debugging or
275           other software development purposes.
276
277           Note that, because the default socket backlog is 5 connections, it
278           may be wise to increase this backlog by calling "set_listen()"
279           before entering "main()" if using this dispatcher.
280

EXPORTS

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

SECURITY CONSIDERATIONS

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

AUTHOR

364       Todd Vierling, <tv@duh.org> <tv@pobox.com>
365

Maintenance

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

SEE ALSO

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

THANKS

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

POD ERRORS

392       Hey! The above document had some coding errors, which are explained
393       below:
394
395       Around line 84:
396           You can't have =items (as at line 128) unless the first thing after
397           the =over is an =item
398
399       Around line 472:
400           You can't have =items (as at line 478) unless the first thing after
401           the =over is an =item
402
403       Around line 993:
404           You forgot a '=back' before '=head1'
405
406       Around line 1059:
407           =back without =over
408
409
410
411perl v5.34.0                      2022-01-21              Sendmail::PMilter(3)
Impressum