1MIMEDEFANG-PROTOCOL(7) Miscellaneous Information Manual MIMEDEFANG-PROTOCOL(7)
2
6 mimedefang-protocol - Conventions used by mimedefang(8) to communicate
7 with filter programs.
8
11 mimedefang(8) and mimedefang-multiplexor(8) provide a simplified mecha‐
12 nism for hooking scripts and programs into Sendmail's milter API.
13 The milter API is multi-threaded and written in C; mimedefang lets you
15 write single-threaded filters written in the language of your choice.
16 Some of the flexibility and speed of milter is sacrificed, but the ease
17 of writing filters more than compensates for this slight loss.
18 This manual describes how mimedefang communicates with the filter pro‐
20 gram, and gives you enough information to write your own filter program
21 as a replacement for mimedefang.pl if you wish.
22
25 The protocol is a simple file-based protocol. For each invocation of a
26 filter, mimedefang creates a unique working directory and populates it
27 with files. It calls the filter, which is expected to populate the
28 working directory with more files, which communicate the scan results
29 back to mimedefang. This simple mechanism allows you to easily write
30 filters in scripting languages without worrying about C-level details.
31
34 The filter program may be invoked in one of five ways:
35 filter_prog directory
38 If the program is invoked with a single argument which is an ab‐
39 solute path name (called the working directory, the program is
40 expected to perform filtering in that directory and then exit.
41 filter_prog -server
44 If the program is invoked with the single argument -server, it
45 is expected to run as a server. See SERVER MODE for details.
46 filter_prog -serveru
49 If the program is invoked with the single argument -serveru, it
50 is expected to run as a server. In addition, anything it prints
51 to file descriptor 3 is used to update the "worker status" field
52 in the multiplexor. This lets the filter inform administrators
53 exactly what it is doing. (See the -Z option to mimedefang-mul‐
54 tiplexor.)
55 filter_prog -embserver
58 Similar to -server, but used by the embedded Perl code. The
59 program should run any initialization routines and then exit.
60 The multiplexor will subsequently call the Perl routine
61 do_main_loop when it is time for the worker to begin running in
62 server mode.
63 filter_prog -embserveru
66 Similar to -embserver with the additional magic of updating the
67 worker status from data written to file descriptor 3.
68
71 When the filter begins a scan, it should change directories to the
72 working directory. In that directory, it will find the following
73 files.
74 INPUTMSG
77 A file containing the complete input e-mail message, including
78 headers.
79 HEADERS
82 A file containing just the headers, one per line. Headers which
83 are continued over several lines in the original message are
84 collapsed into a single line in this file.
85 COMMANDS
88 A file containing a list of commands. Each command is a single
89 letter and may be followed by arguments. Each command is on its
90 own line.
91
94 All commands have their arguments encoded as follows: All characters
95 outside the range 33 to 126 ASCII, as well as the characters "%", "\",
96 "'" and double-quote, are replaced by a percent sign followed by two
97 hex digits specifying the character's numerical value. The filter must
98 un-escape the arguments when it reads the COMMANDS file.
99 The commands from the C to Perl filters are:
102 Ssender
105 The sender of the message.
106 sesmtp_arg
109 An ESMTP argument associated with the sender (such as
110 SIZE=54432). There is one s line for each ESMTP argument.
111 Usubject
114 The message subject.
115 Xmessage_id
118 The Message-ID.
119 Rrecipient mailer host addr
122 A recipient. There is one R line for each recipient. The
123 mailer, host and addr parts of the line are the values of the
124 Sendmail {rcpt_mailer}, {rcpt_host} and {rcpt_addr} macros if
125 they are available, or "?" if not.
126 resmtp_arg
129 An ESMTP argument associated with the most recent recipient
130 (such as NOTIFY=never). There is one r line for each SMTP argu‐
131 ment.
132 ! If this command is present, there are suspicious characters in
135 the message headers.
136 ? If this command is present, there are suspicious characters in
139 the message body.
140 Ihost_addr
143 The SMTP relay host's IP address in dotted-quad notation.
144 iidentifier
147 An identifier generated by MIMEDefang. On a given host, this
148 identifier is very likely to be unique over a timespan of about
149 24 years.
150 Jhost_addr
153 The "real" SMTP relay host's IP address in dotted-quad notation.
154 Multi-stage MIMEDefang relays can use a special IP validation
155 header so that even the innermost MIMEDefang relay can see the
156 "original" relay's IP address.
157 Hhost_name
160 The SMTP relay host name.
161 Eargument
164 The argument to the SMTP "EHLO" or "HELO" command.
165 Qqid The message's Sendmail queue-ID.
168 =macro val
171 Set the value of the specified Sendmail macro to val. Both
172 macro and val are percent-encoded, but the single space charac‐
173 ter between them is not.
174
177 When the filter performs a scan, it can make use of all the information
178 in the files mentioned previously. If the filter needs temporary work‐
179 ing files, it should create a subdirectory under the working directory
180 for its own use. In this case, you do not have to clean up your work‐
181 ing files, because mimedefang deletes the working directory when the
182 filter returns.
183
186 The filter communicates the results of the scan back to mimedefang by
187 creating additional files in the working directory. The most important
188 file is called RESULTS, and it contains a list of one-letter, one-line
189 commands back to the filter. As usual, command arguments are percent-
190 escaped. The commands from the filter back to mimedefang are:
191 Bcode dsn reply_text
194 Bounce (reject) the message with the specified SMTP reply code,
195 DSN code and reply text.
196 D Silently discard the message and pretend it was delivered.
199 Tcode dsn reply_text
202 Return an SMTP temporary failure code with the specified SMTP
203 code, DSN and reply text.
204 C Replace the message body. If this command is present, the file
207 NEWBODY must contain the new message body.
208 Mheader_val
211 Replace the MIME Content-Type header with a new value. Used to
212 change MIME boundaries or convert non-MIME to MIME messages.
213 Hheader val
216 Add a new header header with value val. The header should not
217 contain a colon. Each of header and val is percent-escaped, but
218 the single space between them is not.
219 Nheader index val
222 Adds a new header header with value val in position index. An
223 index of zero specifies that the new header should be prepended
224 before all existing headers.
225 Iheader index val
228 Replace the index'th occurrence of header with value val. The
229 index is 1-based. The header should not contain a colon. Each
230 of header, index and val is percent-escaped, but the single
231 space between them is not.
232 Jheader index
235 Delete the index'th occurrence of header.
236 Rrecip Add a new recipient recip to the message.
239 Srecip Delete recip from the list of message recipients.
242 fsender
245 Change the envelope sender to sender. This is only supported by
246 Sendmail 8.14.0 and higher.
247 F Indicate that we have finished issuing commands. Anything after
250 an F line is ignored.
251
254 In server mode, mimedefang-multiplexor runs the filter program continu‐
255 ously in a server loop. The filter program reads commands from stan‐
256 dard input, and writes results to standard output. The filter program
257 must exit shortly after it sees EOF on its standard input. If it does
258 not exit within 10 seconds, it will be terminated with SIGTERM. If
259 that still does not work, then after a further 10 seconds, it is killed
260 with SIGKILL.
261 SERVER COMMANDS
264 All server commands are single line commands. Each command is
266 followed by a space-separated list of arguments; each argument
267 is percent-encoded. The commands defined are:
268 ping Elicits a reply of "PONG" from the server.
271 scan queue_id dir
274 Run a scan for the mail identiefied by the Sendmail queue-ID
275 queue_id in the directory dir. The command is terminated with a
276 newline. The server must write a newline-terminated "ok" if the
277 scan completed successfully, or "error: msg" if something went
278 wrong.
279 relayok ip_addr hostname client_port daemon_ip daemon_port
282 Test whether or not to accept a connection from the specified
283 host. The server must write "ok 1" if we will accept the con‐
284 nection, or "ok 0 error_message code dsn" if not. It can indi‐
285 cate a temporary failure by writing "ok -1 error_message code
286 dsn". Note that even if the connection is accepted, a later
287 scan can still reject the message based on other criteria.
288 "ip_addr" is the IP address of the relay and "hostname" is the
289 hostname (if it could be determined; otherwise, the IP address
290 in square brackets).
291 helook ip_addr hostname helo_string client_port daemon_ip daemon_port
294 Test whether or not to accept the HELO/EHLO command. The server
295 must write "ok 1" if we will accept the mail attempt, or "ok 0
296 error_message code dsn" if not. "ok -1 error_message code dsn"
297 indicates a temporary failure. helo_string is the argument to
298 the HELO/EHLO command. The remaining arguments have the same
299 meaning as in relayok.
300 senderok sender_addr ip_addr hostname helo_string dir queue_id
303 [esmtp_args...]
304 Test whether or not to accept mail from the specified sender.
306 The server must write "ok 1" if we will accept the mail attempt,
307 or "ok 0 error_message code dsn" if not. "ok -1 error_message
308 code dsn" indicates a temporary failure. Note that even if the
309 sender is accepted, a later scan can still reject the message
310 based on other criteria. "sender_addr" is the sender's e-mail
311 address. The "ip_addr" and "hostname" arguments are as in re‐
312 layok. "helo_string" is the argument to the SMTP HELO/EHLO com‐
313 mand. "dir" is the MIMEDefang spool directory, and "queue_id" is
314 the Sendmail queue identifier.
315 The optional "esmtp_args" are space-separated, percent-encoded
317 ESMTP arguments supplied with the MAIL FROM: command.
318 recipok recip_addr sender_addr ip_addr hostname first_recip helo_string
321 dir queue_id [esmtp_args...]
322 Test whether or not to accept mail for the specified recipient.
323 The server must write "ok 1" if we will accept it, or "ok 0 er‐
324 ror_message code dsn" if not. ok -1 error_message code dsn" in‐
325 dicates a temporary-failure.
326 "recip_addr" is the argument to the RCPT TO: command, and
328 "first_recip" is the argument to the first RCPT TO: command for
329 this message. Other arguments are as in senderok.
330 map map_name key
333 If you are using a map socket (the -N option to mimedefang-mul‐
334 tiplexor), then the server should look up the key key in the map
335 map_name. The server should print a single line to standard
336 output. The first word on the line should be one of OK, NOT‐
337 FOUND, TEMP, TIMEOUT or PERM, indicating a successful lookup,
338 absence of the key, a temporary failure, a timeout or a perma‐
339 nent failure, respectively. This should be followed by a space
340 and a percent-encoded string representing the value of the key
341 (if it was found) or an optional error message (if something
342 went wrong.)
343 tick band
346 The filter should run filter_tick with the specified band argu‐
347 ment. It should print a single line to standard output:
348 tock band
350 Additional Commands
353 The filter can define a function filter_unknown_cmd that can ex‐
354 tend the list of server commands. If you do this, make sure all
355 of your commands start with an upper-case letter to avoid con‐
356 flicts if more built-in commands are defined in the future.
357 SERVER REPLIES
360 The reply codes are:
362 ok [return_code] [parameters]
365 The operation completed successfully. Some operations have an
366 associated return code, and possibly other parameters as well.
367 See the source code for the gory details.
368 error: Message
371 The operation failed. Message may give additional details.
372 In server mode, you should not write anything to standard output except
375 reply codes, or the multiplexor will become confused. You should not
376 terminate the program in server mode; simply echo an error: reply and
377 return to the server loop.
378 When you send a reply code back to the multiplexor, be sure to termi‐
380 nate it with a newline, and to flush standard output. If your program
381 uses the Standard I/O library, standard output may not be flushed imme‐
382 diately, and mimedefang-multiplexor will wait forever for the filter's
383 reply, and eventually kill the filter on the assumption it has hung up.
384 In server mode, if the filter program receives a SIGINT signal, it must
386 terminate. This is used by mimedefang-multiplexor to terminate workers
387 after they have processed a given number of e-mail messages.
388
391 mimedefang was written by Dianne Skoll <dfs@roaringpenguin.com>. The
392 mimedefang home page is https://www.mimedefang.org/.
393
396 mimedefang.pl(8), mimedefang(8), mimedefang-multiplexor(8), mimedefang-
397 filter(5)
3984th Berkeley Distribution 8 February 2005 MIMEDEFANG-PROTOCOL(7)