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()".
88 This is only useful when called from within the dispatcher, as it
89 is not 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
203 "accept()" should be called. HANDLER is a subroutine reference
204 which should 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
218 explicitly 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
230 to 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
247 returned. Otherwise the default pathname "/etc/mail/sendmail.cf"
248 is returned.
249 get_sendmail_class(CLASS[, CONFIG])
251 Returns a list containing all members of the Sendmail class CLASS,
252 in Sendmail configuration file CONFIG (default
253 "/etc/mail/sendmail.cf" or whatever is set by "set_sendmail_cf()").
254 Typically this is used to look up the entries in class "w", the
255 local hostnames class.
256 get_sendmail_option(OPTION[, CONFIG])
258 Returns a list containing the first occurrence of Sendmail option
259 OPTION in Sendmail configuration file CONFIG (default
260 "/etc/mail/sendmail.cf", or whatever has been set by
261 "set_sendmail_cf()"). Returns the value of the option or undef if
262 it is not found. This can be used to learn configuration
263 parameters such as Milter.maxdatasize.
264 set_sendmail_cf(FILENAME)
266 Set the default filename used by "auto_getconn", "auto_setconn",
267 and "sendmail_class" to find Sendmail-specific configuration data.
268 If not explicitly set by this method, it defaults to
269 "/etc/mail/sendmail.cf". Returns 1.
270
272 Milter requests may be dispatched to the protocol handler in a
273 pluggable manner (see the description for the "set_dispatcher()" method
274 above). "Sendmail::PMilter" offers some off-the-shelf dispatchers that
275 use different methods of resource allocation.
276 Each of these is referenced as a non-object function, and return a
278 value that may be passed directly to "set_dispatcher()".
279 Sendmail::PMilter::ithread_dispatcher()
281 (environment) PMILTER_DISPATCHER=ithread
282 June 2019: This dispatcher has not been tested adequately.
283 The "ithread" dispatcher spins up a new thread upon each connection
285 to the milter socket. This provides a thread-based model that may
286 be more resource efficient than the similar "postfork" dispatcher.
287 This requires that the Perl interpreter be compiled with
288 "-Duseithreads", and uses the "threads" module (available on Perl
289 5.8 or later only).
290 Sendmail::PMilter::prefork_dispatcher([PARAMS])
292 (environment) PMILTER_DISPATCHER=prefork
293 June 2019: This dispatcher has been tested extensively by the
294 maintainer.
295 The "prefork" dispatcher forks the main Perl process before
297 accepting connections, and uses the main process to monitor the
298 children. This should be appropriate for steady traffic flow
299 sites. Note that if MAXINTERP is not set in the call to "main()"
300 or in PARAMS, an internal default of 10 processes will be used;
301 similarly, if MAXREQ is not set, 100 requests will be served per
302 child.
303 Currently the child process pool is fixed in size: discarded
305 children will be replaced immediately.
306 PARAMS, if specified, is a hash of key-value pairs defining
308 parameters for the dispatcher. The available parameters that may
309 be set are:
310 child_init
312 subroutine reference that will be called after each child process
313 is forked. It will be passed the "MILTER" object.
314 child_exit
316 subroutine reference that will be called just before each child
317 process terminates. It will be passed the "MILTER" object.
318 max_children
320 Maximum number of child processes active at any time. Equivalent
321 to the MAXINTERP option to main() -- if not set in the main()
322 call, this value will be used.
323 max_requests_per_child
325 Maximum number of requests a child process may service before
326 being recycled. Equivalent to the MAXREQ option to main() -- if
327 not set in the main() call, this value will be used.
328 Sendmail::PMilter::postfork_dispatcher()
330 (environment) PMILTER_DISPATCHER=postfork
331 June 2019: This dispatcher has not been tested adequately.
332 This is the default dispatcher for PMilter if no explicit
334 dispatcher is set.
335 The "postfork" dispatcher forks the main Perl process upon each
337 connection to the milter socket. This is adequate for machines
338 that get bursty but otherwise mostly idle mail traffic, as the
339 idle-time resource consumption is very low.
340 If the maximum number of interpreters is running when a new
342 connection comes in, this dispatcher blocks until a slot becomes
343 available for a new interpreter.
344 Sendmail::PMilter::sequential_dispatcher()
346 (environment) PMILTER_DISPATCHER=sequential
347 June 2019: This dispatcher has not been tested adequately.
348 The "sequential" dispatcher forces one request to be served at a
350 time, making other requests wait on the socket for the next pass
351 through the loop. This is not suitable for most production
352 installations, but may be quite useful for milter debugging or
353 other software development purposes.
354 Note that, because the default socket backlog is 5 connections, if
356 you use this dispatcher it may be wise to increase this backlog by
357 calling "set_listen()" before entering "main()".
358
360 Each of these symbols may be imported explicitly, imported with tag
361 ":all", or referenced as part of the "Sendmail::PMilter::" package.
362 Callback Return Values
364 SMFIS_CONTINUE - continue processing the message
365 SMFIS_REJECT - reject the message with a 5xx error
366 SMFIS_DISCARD - accept, but discard the message
367 SMFIS_ACCEPT - accept the message without further processing
368 SMFIS_TEMPFAIL - reject the message with a 4xx error
369 SMFIS_MSG_LOOP - send a never-ending response to the HELO command
370 In the "envrcpt" callback, SMFIS_REJECT and SMFIS_TEMPFAIL will
372 reject only the current recipient. Message processing will continue
373 for any other recipients as if SMFIS_CONTINUE had been returned.
374 In all callbacks, SMFIS_CONTINUE tells the MTA to continue calling
376 the milter (and any other milters which may be installed), for the
377 remaining message steps. Except as noted for the "envrcpt" callback,
378 all the other return values terminate processing of the message by
379 all the installed milters. Message disposal is according to the
380 return value.
381
383 Running as root
384 Running Perl as root is dangerous. Running "Sendmail::PMilter" as
385 root may well be system-assisted suicide at this point. So don't
386 do that.
387 More specifically, though, it is possible to run a milter frontend
389 as root, in order to gain access to network resources (such as a
390 filesystem socket in /var/run), and then drop privileges before
391 accepting connections. To do this, insert drop-privileges code
392 between calls to setconn/auto_setconn and main; for instance:
393 $milter->auto_setconn('pmilter');
395 $> = 65534; # drop root privileges
396 $milter->main();
397 The semantics of properly dropping system administrator privileges
399 in Perl are, unfortunately, somewhat OS-specific, so this process
400 is not described in detail here.
401
403 Todd Vierling, Ged Haywood.
404
406 cpan:GWHAYWOOD now maintains Sendmail::PMilter. Use the CPAN issue
407 tracking system to request more information, or to comment. Private
408 mail is fine but you'll need to use the right email address, it should
409 be obvious. This module is NOT maintained on Sourceforge/Github/etc..
410
412 Sendmail::PMilter::Context
413 The Sendmail documentation, especially libmilter/docs/* in the sources
415 of Sendmail version 8.15.2 and later.
416
418 rob.casey@bluebottle.com - for the prefork mechanism idea
419perl v5.36.0 2022-10-31 Sendmail::PMilter(3)