1Sendmail::PMilter(3) User Contributed Perl Documentation Sendmail::PMilter(3)
2
6 Copyright (c) 2016-2022 G.W. Haywood. All rights reserved.
7 With thanks to all those who have trodden these paths before,
8 including Copyright (c) 2002-2004 Todd Vierling. All rights
9 reserved.
10 Redistribution and use in source and binary forms, with or without
12 modification, are permitted provided that the following conditions are
13 met:
14 1. Redistributions of source code must retain the above copyright
16 notices, this list of conditions and the following disclaimer.
17 2. Redistributions in binary form must reproduce the above copyright
19 notices, this list of conditions and the following disclaimer in the
20 documentation and/or other materials provided with the distribution.
21 3. Neither the name of the author nor the names of contributors may be
23 used to endorse or promote products derived from this software without
24 specific prior written permission. In the case of G.W. Haywood this
25 permission is hereby now granted.
26 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
28 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
29 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
30 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
31 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
32 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
33 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
34 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
35 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
36 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
37 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
38
40 Sendmail::PMilter - Perl binding of Sendmail Milter protocol
41
43 use Sendmail::PMilter;
44 my $milter = new Sendmail::PMilter;
46 $milter->auto_setconn(NAME);
48 $milter->register(NAME, { CALLBACKS }[, FLAGS]);
49 $milter->main();
50
52 Sendmail::PMilter is a mail filtering API implementing the Sendmail
53 Milter Protocol in Perl. This allows the administrator of Sendmail
54 (and perhaps other MTAs which implement the Milter Protocol) to use
55 pure Perl code to filter and modify mail during an SMTP connection.
56 Over the years, the protocol which governs the communication between
58 qSendmail and its milters has passed through a number of revisions.
59 This documentation is for Sendmail::PMilter versions 1.20 and later,
61 which now supports Milter Protocol Version 6. This is a substantial
62 upgrade from earlier versions, which at best supported up to Milter
63 Protocol Version 2 - this was first seen in Sendmail version 8.14.0
64 which was released on January 31st 2007.
65 Sendmail::PMilter now uses neither the original Sendmail::Milter (it is
67 obsolete, badly flawed and unmaintained) nor the Sendmail::Milter which
68 was packaged with earlier versions of Sendmail::PMilter as a temporary
69 workaround for the broken original.
70 For communications between the MTA and the milter, a 'dispatcher' acts
72 as a go-between. This must be chosen when the milter is initialized,
73 before it serves requests. Several dispatchers are provided within the
74 Sendmail::PMilter module, but in versions before 1.20 all the
75 dispatchers suffered from issues of varying gravity. The 'prefork'
76 dispatcher (see DISPATCHERS below) has now been extensively exercised
77 by the current maintainer, but although the others have been patched
78 from issue reports going back more than a decade from the time of
79 writing (June 2019) THEY HAVE NOT BEEN TESTED. Feedback via the CPAN
80 issue tracking system is encouraged. If you have developed your own
81 dispatcher you can either pass a code reference to set_dispatcher() or
82 set an environment variable to point to it. Sendmail::PMilter will
83 then use it instead of a built-in dispatcher.
84
86 get_max_interpreters()
87 Returns the maximum number of interpreters passed to main(). This
88 is only useful when called from within the dispatcher, as it is not
89 set before main() is called.
90 get_max_requests()
92 Returns the maximum number of requests per interpreter passed to
93 main(). This is only useful when called from within the
94 dispatcher, as it is not set before main() is called.
95 main([MAXCHILDREN[, MAXREQ]])
97 This is the last method called in the main block of a milter
98 program. If successful, this call never returns; the protocol
99 engine is launched and begins accepting connections.
100 MAXCHILDREN (default 0, meaning unlimited) specifies the maximum
102 number of connections that may be serviced simultaneously. If a
103 connection arrives with the number of active connections above this
104 limit, the milter will immediately return a temporary failure
105 condition and close the connection. Passing a value for
106 MAXCHILDREN is optional.
107 MAXREQ (default 0, meaning unlimited) is the maximum number of
109 requests that a child may service before being recycled. It is not
110 guaranteed that the interpreter will service this many requests,
111 only that it will not go over the limit. MAXCHILDREN must be given
112 if MAXREQ is to be set.
113 Any callback which "die"s will have its output sent to "warn",
115 followed by a clean shutdown of the milter connection. To catch
116 any warnings generated by the callbacks, and any error messages
117 caused by a "die", set $SIG{__WARN__} to a user-defined subroutine.
118 (See perlvar.)
119 register(NAME, CALLBACKS[, FLAGS])
121 Sets up the main milter loop configuration.
122 NAME is the name of the milter. This should be the same name as
124 passed to auto_getconn() or auto_setconn(), but this PMilter
125 implementation does not enforce this.
126 CALLBACKS is a hash reference containing one or more callback
128 subroutines. For example
129 my %callbacks =
131 (
132 'negotiate' => \&my_negotiate_callback,
133 'connect' => \&my_connect_callback,
134 'helo' => \&my_helo_callback,
135 'envfrom' => \&my_envfrom_callback,
136 'close' => \&my_close_callback,
137 'abort' => \&my_abort_callback,
138 );
139 $milter->register( $milter_name, \%callbacks );
140 If a callback is not named in this hashref, the caller's package
142 will be searched for subroutines named "CALLBACK_callback", where
143 CALLBACK is the name of the callback function.
144 FLAGS is accepted for backward compatibility with older versions of
146 this module. Consider it deprecated. Set it to SMFI_V6_PROT for
147 all available 'actions' in any recent (last few years) Sendmail
148 version.
149 If no "negotiate" callback is registered, then by default the
151 protocol steps available are as described in .../libmilter/engine.c
152 in the Sendmail sources. This means all the registered CALLBACKS
153 plus the SKIP function call which is allowed in the End Of Message
154 callback. Note that SMFIP_RCPT_REJ is specifically not included.
155 register() must be called successfully exactly once. If called a
157 second time, the previously registered callbacks will be erased.
158 Returns 1 on success, undef on failure.
160 setconn(DESC)
162 Sets up the server socket with connection descriptor DESC. This is
163 identical to the descriptor syntax used by the "X" milter
164 configuration lines in sendmail.cf (if using Sendmail). This
165 should be one of the following:
166 local:PATH
168 A local ("UNIX") socket on the filesystem, named PATH. This has
169 some smarts that will auto-delete the pathname if it seems that
170 the milter is not currently running (but this currently contains
171 a race condition that may not be fixable; at worst, there could
172 be two milters running with one never receiving connections).
173 inet:PORT[@HOST]
175 An IPv4 socket, bound to address HOST (default INADDR_ANY), on
176 port PORT. It is not recommended to open milter engines to the
177 world, so the @HOST part should be specified.
178 inet6:PORT[@HOST]
180 An IPv6 socket, bound to address HOST (default INADDR_ANY), on
181 port PORT. This requires IPv6 support and the Perl
182 IO::Socket::IP package to be installed. It is not recommended to
183 open milter engines to the world, so the @HOST part should be
184 specified.
185 Returns a true value on success, undef on failure.
187 set_dispatcher(CODEREF)
189 Sets the dispatcher used to accept socket connections and hand them
190 off to the protocol engine. This allows pluggable resource
191 allocation so that the milter script may use fork, threads, or any
192 other such means of handling milter connections. See "DISPATCHERS"
193 below for more information.
194 The subroutine (code) reference will be called by main() when the
196 listening socket object is prepared and ready to accept
197 connections. It will be passed the arguments:
198 MILTER, LSOCKET, HANDLER
200 MILTER is the milter object currently running. LSOCKET is a
202 listening socket (an instance of "IO::Socket"), upon which accept()
203 should be called. HANDLER is a subroutine reference which should
204 be called, passing the socket object returned by
205 "LSOCKET->accept()".
206 Note that the dispatcher may also be set from one of the off-the-
208 shelf dispatchers noted in this document by setting the
209 PMILTER_DISPATCHER environment variable. See "DISPATCHERS", below.
210 set_listen(BACKLOG)
212 Set the socket listen backlog to BACKLOG. The default is 5
213 connections if not set explicitly by this method. Only useful
214 before calling main().
215 set_socket(SOCKET)
217 Rather than calling setconn(), this method may be called explicitly
218 to set the "IO::Socket" instance used to accept inbound
219 connections.
220
222 The following methods are only useful if Sendmail is the MTA connecting
223 to this milter. Other MTAs likely don't use Sendmail's configuration
224 file, so these methods would not be useful with them.
225 auto_getconn(NAME[, CONFIG])
227 Returns the connection descriptor for milter NAME in Sendmail
228 configuration file CONFIG (default "/etc/mail/sendmail.cf" or
229 whatever was set by set_sendmail_cf()). This can then be passed to
230 setconn(), below.
231 Returns a true value on success, undef on failure.
233 auto_setconn(NAME[, CONFIG])
235 Creates the server connection socket for milter NAME in Sendmail
236 configuration file CONFIG.
237 Essentially, does:
239 $milter->setconn($milter->auto_getconn(NAME, CONFIG))
241 Returns a true value on success, undef on failure.
243 get_sendmail_cf()
245 Returns the pathname of the Sendmail configuration file. If this
246 has been set by set_sendmail_cf(), then that is the value returned.
247 Otherwise the default pathname "/etc/mail/sendmail.cf" is returned.
248 get_sendmail_class(CLASS[, CONFIG])
250 Returns a list containing all members of the Sendmail class CLASS,
251 in Sendmail configuration file CONFIG (default
252 "/etc/mail/sendmail.cf" or whatever is set by set_sendmail_cf()).
253 Typically this is used to look up the entries in class "w", the
254 local hostnames class.
255 get_sendmail_option(OPTION[, CONFIG])
257 Returns a list containing the first occurrence of Sendmail option
258 OPTION in Sendmail configuration file CONFIG (default
259 "/etc/mail/sendmail.cf", or whatever has been set by
260 set_sendmail_cf()). Returns the value of the option or undef if it
261 is not found. This can be used to learn configuration parameters
262 such as Milter.maxdatasize.
263 set_sendmail_cf(FILENAME)
265 Set the default filename used by "auto_getconn", "auto_setconn",
266 and "sendmail_class" to find Sendmail-specific configuration data.
267 If not explicitly set by this method, it defaults to
268 "/etc/mail/sendmail.cf". Returns 1.
269
271 Milter requests may be dispatched to the protocol handler in a
272 pluggable manner (see the description for the set_dispatcher() method
273 above). "Sendmail::PMilter" offers some off-the-shelf dispatchers that
274 use different methods of resource allocation.
275 Each of these is referenced as a non-object function, and return a
277 value that may be passed directly to set_dispatcher().
278 Sendmail::PMilter::ithread_dispatcher()
280 (environment) PMILTER_DISPATCHER=ithread
281 June 2019: This dispatcher has not been tested adequately.
282 The "ithread" dispatcher spins up a new thread upon each connection
284 to the milter socket. This provides a thread-based model that may
285 be more resource efficient than the similar "postfork" dispatcher.
286 This requires that the Perl interpreter be compiled with
287 "-Duseithreads", and uses the "threads" module (available on Perl
288 5.8 or later only).
289 Sendmail::PMilter::prefork_dispatcher([PARAMS])
291 (environment) PMILTER_DISPATCHER=prefork
292 June 2019: This dispatcher has been tested extensively by the
293 maintainer.
294 The "prefork" dispatcher forks the main Perl process before
296 accepting connections, and uses the main process to monitor the
297 children. This should be appropriate for steady traffic flow
298 sites. Note that if MAXINTERP is not set in the call to main() or
299 in PARAMS, an internal default of 10 processes will be used;
300 similarly, if MAXREQ is not set, 100 requests will be served per
301 child.
302 Currently the child process pool is fixed in size: discarded
304 children will be replaced immediately.
305 PARAMS, if specified, is a hash of key-value pairs defining
307 parameters for the dispatcher. The available parameters that may
308 be set are:
309 child_init
311 subroutine reference that will be called after each child process
312 is forked. It will be passed the "MILTER" object.
313 child_exit
315 subroutine reference that will be called just before each child
316 process terminates. It will be passed the "MILTER" object.
317 max_children
319 Maximum number of child processes active at any time. Equivalent
320 to the MAXINTERP option to main() -- if not set in the main()
321 call, this value will be used.
322 max_requests_per_child
324 Maximum number of requests a child process may service before
325 being recycled. Equivalent to the MAXREQ option to main() -- if
326 not set in the main() call, this value will be used.
327 Sendmail::PMilter::postfork_dispatcher()
329 (environment) PMILTER_DISPATCHER=postfork
330 June 2019: This dispatcher has not been tested adequately.
331 This is the default dispatcher for PMilter if no explicit
333 dispatcher is set.
334 The "postfork" dispatcher forks the main Perl process upon each
336 connection to the milter socket. This is adequate for machines
337 that get bursty but otherwise mostly idle mail traffic, as the
338 idle-time resource consumption is very low.
339 If the maximum number of interpreters is running when a new
341 connection comes in, this dispatcher blocks until a slot becomes
342 available for a new interpreter.
343 Sendmail::PMilter::sequential_dispatcher()
345 (environment) PMILTER_DISPATCHER=sequential
346 June 2019: This dispatcher has not been tested adequately.
347 The "sequential" dispatcher forces one request to be served at a
349 time, making other requests wait on the socket for the next pass
350 through the loop. This is not suitable for most production
351 installations, but may be quite useful for milter debugging or
352 other software development purposes.
353 Note that, because the default socket backlog is 5 connections, if
355 you use this dispatcher it may be wise to increase this backlog by
356 calling set_listen() before entering main().
357
359 Each of these symbols may be imported explicitly, imported with tag
360 ":all", or referenced as part of the "Sendmail::PMilter::" package.
361 Callback Return Values
363 SMFIS_CONTINUE - continue processing the message
364 SMFIS_REJECT - reject the message with a 5xx error
365 SMFIS_DISCARD - accept, but discard the message
366 SMFIS_ACCEPT - accept the message without further processing
367 SMFIS_TEMPFAIL - reject the message with a 4xx error
368 SMFIS_MSG_LOOP - send a never-ending response to the HELO command
369 In the "envrcpt" callback, SMFIS_REJECT and SMFIS_TEMPFAIL will
371 reject only the current recipient. Message processing will continue
372 for any other recipients as if SMFIS_CONTINUE had been returned.
373 In all callbacks, SMFIS_CONTINUE tells the MTA to continue calling
375 the milter (and any other milters which may be installed), for the
376 remaining message steps. Except as noted for the "envrcpt" callback,
377 all the other return values terminate processing of the message by
378 all the installed milters. Message disposal is according to the
379 return value.
380
382 Running as root
383 Running Perl as root is dangerous. Running "Sendmail::PMilter" as
384 root may well be system-assisted suicide at this point. So don't
385 do that.
386 More specifically, though, it is possible to run a milter frontend
388 as root, in order to gain access to network resources (such as a
389 filesystem socket in /var/run), and then drop privileges before
390 accepting connections. To do this, insert drop-privileges code
391 between calls to setconn/auto_setconn and main; for instance:
392 $milter->auto_setconn('pmilter');
394 $> = 65534; # drop root privileges
395 $milter->main();
396 The semantics of properly dropping system administrator privileges
398 in Perl are, unfortunately, somewhat OS-specific, so this process
399 is not described in detail here.
400
402 Todd Vierling, Ged Haywood.
403
405 cpan:GWHAYWOOD now maintains Sendmail::PMilter. Use the CPAN issue
406 tracking system to request more information, or to comment. Private
407 mail is fine but you'll need to use the right email address, it should
408 be obvious. This module is NOT maintained on Sourceforge/Github/etc..
409
411 Sendmail::PMilter::Context
412 The Sendmail documentation, especially libmilter/docs/* in the sources
414 of Sendmail version 8.15.2 and later.
415
417 rob.casey@bluebottle.com - for the prefork mechanism idea
418perl v5.36.0 2023-01-20 Sendmail::PMilter(3)