1Sendmail::PMilter(3) User Contributed Perl Documentation Sendmail::PMilter(3)
2
6 Sendmail::PMilter - Perl binding of Sendmail Milter protocol
7
9 use Sendmail::PMilter;
10 my $milter = new Sendmail::PMilter;
12 $milter->auto_setconn(NAME);
14 $milter->register(NAME, { CALLBACKS }, FLAGS);
15 $milter->main();
16
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 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
30 get_max_interpreters()
31 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 get_max_requests()
37 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 main([MAXCHILDREN[, MAXREQ]])
43 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 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 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 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 register(NAME, CALLBACKS[, FLAGS])
66 Sets up the main milter loop configuration.
68 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 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 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 "register()" must be called successfully exactly once. If called a
88 second time, the previously registered callbacks will be erased.
89 Returns a true value on success, undef on failure.
91 setconn(DESC)
93 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 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 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 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 Returns a true value on success, undef on failure.
118 set_dispatcher(CODEREF)
120 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 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 MILTER, LSOCKET, HANDLER
132 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 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 set_listen(BACKLOG)
144 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 set_socket(SOCKET)
150 Rather than calling "setconn()", this method may be called
152 explicitly to set the "IO::Socket" instance used to accept inbound
153 connections.
154
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 auto_getconn(NAME[, CONFIG])
161 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 Returns a true value on success, undef on failure.
168 auto_setconn(NAME[, CONFIG])
170 Creates the server connection socket for milter NAME in Sendmail
172 configuration file CONFIG.
173 Essentially, does:
175 $milter->setconn($milter->auto_getconn(NAME, CONFIG))
177 Returns a true value on success, undef on failure.
179 get_sendmail_cf()
181 Returns the pathname of the Sendmail configuration file set by
183 "set_sendmail_cf()", else the default of "/etc/mail/sendmail.cf".
184 get_sendmail_class(CLASS[, CONFIG])
186 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 set_sendmail_cf(FILENAME)
194 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
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 Each of these is referenced as a non-object function, and return a
207 value that may be passed directly to "set_dispatcher()".
208 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 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 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 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 child_init
238 subroutine reference that will be called after each child process
239 is forked. It will be passed the "MILTER" object.
240 child_exit
242 subroutine reference that will be called just before each child
243 process terminates. It will be passed the "MILTER" object.
244 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 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 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 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 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 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
278 Each of these symbols may be imported explicitly, imported with tag
279 ":all", or referenced as part of the "Sendmail::PMilter::" package.
280 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 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 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 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 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 SMFIF_QUARANTINE - allow $ctx->quarantine()
312 (requires Sendmail 8.13; not defined in Sendmail::Milter)
313 SMFIF_SETSENDER - allow $ctx->setsender()
315 (requires special Sendmail patch; see below[*])
316 SMFI_V1_ACTS - SMFIF_ADDHDRS through SMFIF_DELRCPT
318 (Sendmail 8.11 _FFR_MILTER capabilities)
319 SMFI_V2_ACTS - SMFIF_ADDHDRS through SMFIF_CHGHDRS
321 SMFI_CURR_ACTS - (compatibility synonym for SMFI_V2_ACTS)
322 (Sendmail 8.12 capabilities)
323 (Currently no combined macro includes SMFIF_QUARANTINE or
325 SMFIF_SETSENDER.)
326 [*] 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 C<http://www.sourceforge.net/projects/mlfi-setsender>
332 Additionally, the following statement must appear after the "use"
334 statements in your milter program; otherwise, setsender() will always
335 fail when called:
336 local $Sendmail::PMilter::enable_setsender = 1;
338
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 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 $milter->auto_setconn('pmilter');
352 $> = 65534; # drop root privileges
353 $milter->main();
354 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
360 Todd Vierling, <tv@duh.org> <tv@pobox.com>
361
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 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 · Fork it & fix it on GitHub at
373 http://github.com/avar/sendmail-pmilter
374 <http://github.com/avar/sendmail-pmilter>
375 · Send AVAR an E-Mail requesting upload permissions so you can upload
377 the fixed version to the CPAN.
378
380 Sendmail::PMilter::Context for a description of the arguments passed to
381 each callback function
382 The project homepage: http://pmilter.sourceforge.net/
384
386 rob.casey@bluebottle.com - for the prefork mechanism idea
387
389 Hey! The above document had some coding errors, which are explained
390 below:
391 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 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 Around line 979:
401 You forgot a '=back' before '=head1'
402 Around line 1045:
404 =back without =over
405perl v5.12.0 2010-03-12 Sendmail::PMilter(3)