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 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 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 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
282 Each of these symbols may be imported explicitly, imported with tag
283 ":all", or referenced as part of the "Sendmail::PMilter::" package.
284 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 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 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 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 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 SMFIF_QUARANTINE - allow $ctx->quarantine()
316 (requires Sendmail 8.13; not defined in Sendmail::Milter)
317 SMFIF_SETSENDER - allow $ctx->setsender()
319 (requires special Sendmail patch; see below[*])
320 SMFI_V1_ACTS - SMFIF_ADDHDRS through SMFIF_DELRCPT
322 (Sendmail 8.11 _FFR_MILTER capabilities)
323 SMFI_V2_ACTS - SMFIF_ADDHDRS through SMFIF_CHGHDRS
325 SMFI_CURR_ACTS - (compatibility synonym for SMFI_V2_ACTS)
326 (Sendmail 8.12 capabilities)
327 (Currently no combined macro includes SMFIF_QUARANTINE or
329 SMFIF_SETSENDER.)
330 [*] 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 C<http://www.sourceforge.net/projects/mlfi-setsender>
336 Additionally, the following statement must appear after the "use"
338 statements in your milter program; otherwise, setsender() will always
339 fail when called:
340 local $Sendmail::PMilter::enable_setsender = 1;
342
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 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 $milter->auto_setconn('pmilter');
356 $> = 65534; # drop root privileges
357 $milter->main();
358 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
364 Todd Vierling, <tv@duh.org> <tv@pobox.com>
365
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 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 • Fork it & fix it on GitHub at
377 <http://github.com/avar/sendmail-pmilter>
378 • Send AVAR an E-Mail requesting upload permissions so you can upload
380 the fixed version to the CPAN.
381
383 Sendmail::PMilter::Context for a description of the arguments passed to
384 each callback function
385 The project homepage: http://pmilter.sourceforge.net/
387
389 rob.casey@bluebottle.com - for the prefork mechanism idea
390
392 Hey! The above document had some coding errors, which are explained
393 below:
394 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 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 Around line 993:
404 You forgot a '=back' before '=head1'
405 Around line 1059:
407 =back without =over
408perl v5.34.0 2022-01-21 Sendmail::PMilter(3)