1MIMEDEFANG-PROTOCOL(7) Miscellaneous Information Manual MIMEDEFANG-PROTOCOL(7)
2
3
4

NAME

6       mimedefang-protocol  - Conventions used by mimedefang(8) to communicate
7       with filter programs.
8
9

DESCRIPTION

11       mimedefang(8) and mimedefang-multiplexor(8) provide a simplified mecha‐
12       nism for hooking scripts and programs into Sendmail's milter API.
13
14       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
19       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
23

PROTOCOL OVERVIEW

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
32

FILTER INVOCATION

34       The filter program may be invoked in one of five ways:
35
36
37       filter_prog directory
38              If  the  program  is  invoked with a single argument which is an
39              absolute path name (called the working directory, the program is
40              expected to perform filtering in that directory and then exit.
41
42
43       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
47
48       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
56
57       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
64
65       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
69

INITIAL FILE LAYOUT

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
75
76       INPUTMSG
77              A file containing the complete input e-mail  message,  including
78              headers.
79
80
81       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
86
87       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
92

THE COMMANDS FILE

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
100
101       The commands from the C to Perl filters are:
102
103
104       Ssender
105              The sender of the message.
106
107
108       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
112
113       Usubject
114              The message subject.
115
116
117       Xmessage_id
118              The Message-ID.
119
120
121       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
127
128       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
133
134       !      If  this  command is present, there are suspicious characters in
135              the message headers.
136
137
138       ?      If this command is present, there are suspicious  characters  in
139              the message body.
140
141
142       Ihost_addr
143              The SMTP relay host's IP address in dotted-quad notation.
144
145
146       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
151
152       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
158
159       Hhost_name
160              The SMTP relay host name.
161
162
163       Eargument
164              The argument to the SMTP "EHLO" or "HELO" command.
165
166
167       Qqid   The message's Sendmail queue-ID.
168
169
170       =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
175

FILTER OPERATION

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
184

FINAL FILE LAYOUT

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
192
193       Bcode dsn reply_text
194              Bounce  (reject) the message with the specified SMTP reply code,
195              DSN code and reply text.
196
197
198       D      Silently discard the message and pretend it was delivered.
199
200
201       Tcode dsn reply_text
202              Return an SMTP temporary failure code with  the  specified  SMTP
203              code, DSN and reply text.
204
205
206       C      Replace  the message body.  If this command is present, the file
207              NEWBODY must contain the new message body.
208
209
210       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
214
215       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
220
221       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
226
227       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
233
234       Jheader index
235              Delete the index'th occurrence of header.
236
237
238       Rrecip Add a new recipient recip to the message.
239
240
241       Srecip Delete recip from the list of message recipients.
242
243
244       fsender
245              Change the envelope sender to sender.  This is only supported by
246              Sendmail 8.14.0 and higher.
247
248
249       F      Indicate that we have finished issuing commands.  Anything after
250              an F line is ignored.
251
252

SERVER MODE

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
262
263       SERVER COMMANDS
264
265              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
269
270       ping   Elicits a reply of "PONG" from the server.
271
272
273       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
280
281       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
292
293       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
301
302       senderok   sender_addr   ip_addr   hostname  helo_string  dir  queue_id
303       [esmtp_args...]
304
305              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
312              relayok.  "helo_string"  is  the  argument to the SMTP HELO/EHLO
313              command. "dir" is the MIMEDefang spool directory, and "queue_id"
314              is the Sendmail queue identifier.
315
316              The  optional  "esmtp_args" are space-separated, percent-encoded
317              ESMTP arguments supplied with the MAIL FROM: command.
318
319
320       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
324              error_message  code  dsn" if not.  ok -1 error_message code dsn"
325              indicates a temporary-failure.
326
327              "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
331
332       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
344
345       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
349              tock band
350
351
352       Additional Commands
353              The filter can define a  function  filter_unknown_cmd  that  can
354              extend  the  list of server commands.  If you do this, make sure
355              all of your commands start with an upper-case  letter  to  avoid
356              conflicts if more built-in commands are defined in the future.
357
358
359       SERVER REPLIES
360
361              The reply codes are:
362
363
364       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
369
370       error: Message
371              The operation failed.  Message may give additional details.
372
373
374       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
379       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
385       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
389

AUTHOR

391       mimedefang was written by Dianne Skoll  <dfs@roaringpenguin.com>.   The
392       mimedefang home page is http://www.mimedefang.org/.
393
394

SEE ALSO

396       mimedefang.pl(8), mimedefang(8), mimedefang-multiplexor(8), mimedefang-
397       filter(5)
398
399
400
401
402
403
4044th Berkeley Distribution       8 February 2005         MIMEDEFANG-PROTOCOL(7)
Impressum