Provided by: mimedefang_2.73-2build1_amd64 
NAME
mimedefang-protocol - Conventions used by mimedefang(8) to communicate with filter
programs.
DESCRIPTION
mimedefang(8) and mimedefang-multiplexor(8) provide a simplified mechanism for hooking
scripts and programs into Sendmail's milter API.
The milter API is multi-threaded and written in C; mimedefang lets you write single-
threaded filters written in the language of your choice. Some of the flexibility and
speed of milter is sacrificed, but the ease of writing filters more than compensates for
this slight loss.
This manual describes how mimedefang communicates with the filter program, and gives you
enough information to write your own filter program as a replacement for mimedefang.pl if
you wish.
PROTOCOL OVERVIEW
The protocol is a simple file-based protocol. For each invocation of a filter, mimedefang
creates a unique working directory and populates it with files. It calls the filter,
which is expected to populate the working directory with more files, which communicate the
scan results back to mimedefang. This simple mechanism allows you to easily write filters
in scripting languages without worrying about C-level details.
FILTER INVOCATION
The filter program may be invoked in one of five ways:
filter_prog directory
If the program is invoked with a single argument which is an absolute path name
(called the working directory, the program is expected to perform filtering in that
directory and then exit.
filter_prog -server
If the program is invoked with the single argument -server, it is expected to run
as a server. See SERVER MODE for details.
filter_prog -serveru
If the program is invoked with the single argument -serveru, it is expected to run
as a server. In addition, anything it prints to file descriptor 3 is used to
update the "slave status" field in the multiplexor. This lets the filter inform
administrators exactly what it is doing. (See the -Z option to mimedefang-
multiplexor.)
filter_prog -embserver
Similar to -server, but used by the embedded Perl code. The program should run any
initialization routines and then exit. The multiplexor will subsequently call the
Perl routine do_main_loop when it is time for the slave to begin running in server
mode.
filter_prog -embserveru
Similar to -embserver with the additional magic of updating the slave status from
data written to file descriptor 3.
INITIAL FILE LAYOUT
When the filter begins a scan, it should change directories to the working directory. In
that directory, it will find the following files.
INPUTMSG
A file containing the complete input e-mail message, including headers.
HEADERS
A file containing just the headers, one per line. Headers which are continued over
several lines in the original message are collapsed into a single line in this
file.
COMMANDS
A file containing a list of commands. Each command is a single letter and may be
followed by arguments. Each command is on its own line.
THE COMMANDS FILE
All commands have their arguments encoded as follows: All characters outside the range 33
to 126 ASCII, as well as the characters "%", "\", "'" and double-quote, are replaced by a
percent sign followed by two hex digits specifying the character's numerical value. The
filter must un-escape the arguments when it reads the COMMANDS file.
The commands from the C to Perl filters are:
Ssender
The sender of the message.
sesmtp_arg
An ESMTP argument associated with the sender (such as SIZE=54432). There is one s
line for each ESMTP argument.
Usubject
The message subject.
Xmessage_id
The Message-ID.
Rrecipient mailer host addr
A recipient. There is one R line for each recipient. The mailer, host and addr
parts of the line are the values of the Sendmail {rcpt_mailer}, {rcpt_host} and
{rcpt_addr} macros if they are available, or "?" if not.
resmtp_arg
An ESMTP argument associated with the most recent recipient (such as NOTIFY=never).
There is one r line for each SMTP argument.
! If this command is present, there are suspicious characters in the message headers.
? If this command is present, there are suspicious characters in the message body.
Ihost_addr
The SMTP relay host's IP address in dotted-quad notation.
iidentifier
An identifier generated by MIMEDefang. On a given host, this identifier is very
likely to be unique over a timespan of about 24 years.
Jhost_addr
The "real" SMTP relay host's IP address in dotted-quad notation. Multi-stage
MIMEDefang relays can use a special IP validation header so that even the innermost
MIMEDefang relay can see the "original" relay's IP address.
Hhost_name
The SMTP relay host name.
Eargument
The argument to the SMTP "EHLO" or "HELO" command.
Qqid The message's Sendmail queue-ID.
=macro val
Set the value of the specified Sendmail macro to val. Both macro and val are
percent-encoded, but the single space character between them is not.
FILTER OPERATION
When the filter performs a scan, it can make use of all the information in the files
mentioned previously. If the filter needs temporary working files, it should create a
subdirectory under the working directory for its own use. In this case, you do not have
to clean up your working files, because mimedefang deletes the working directory when the
filter returns.
FINAL FILE LAYOUT
The filter communicates the results of the scan back to mimedefang by creating additional
files in the working directory. The most important file is called RESULTS, and it
contains a list of one-letter, one-line commands back to the filter. As usual, command
arguments are percent-escaped. The commands from the filter back to mimedefang are:
Bcode dsn reply_text
Bounce (reject) the message with the specified SMTP reply code, DSN code and reply
text.
D Silently discard the message and pretend it was delivered.
Tcode dsn reply_text
Return an SMTP temporary failure code with the specified SMTP code, DSN and reply
text.
C Replace the message body. If this command is present, the file NEWBODY must
contain the new message body.
Mheader_val
Replace the MIME Content-Type header with a new value. Used to change MIME
boundaries or convert non-MIME to MIME messages.
Hheader val
Add a new header header with value val. The header should not contain a colon.
Each of header and val is percent-escaped, but the single space between them is
not.
Nheader index val
Adds a new header header with value val in position index. An index of zero
specifies that the new header should be prepended before all existing headers.
Iheader index val
Replace the index'th occurrence of header with value val. The index is 1-based.
The header should not contain a colon. Each of header, index and val is percent-
escaped, but the single space between them is not.
Jheader index
Delete the index'th occurrence of header.
Rrecip Add a new recipient recip to the message.
Srecip Delete recip from the list of message recipients.
fsender
Change the envelope sender to sender. This is only supported by Sendmail 8.14.0
and higher.
F Indicate that we have finished issuing commands. Anything after an F line is
ignored.
SERVER MODE
In server mode, mimedefang-multiplexor runs the filter program continuously in a server
loop. The filter program reads commands from standard input, and writes results to
standard output. The filter program must exit shortly after it sees EOF on its standard
input. If it does not exit within 10 seconds, it will be terminated with SIGTERM. If
that still does not work, then after a further 10 seconds, it is killed with SIGKILL.
SERVER COMMANDS
All server commands are single line commands. Each command is followed by a space-
separated list of arguments; each argument is percent-encoded. The commands
defined are:
ping Elicits a reply of "PONG" from the server.
scan queue_id dir
Run a scan for the mail identiefied by the Sendmail queue-ID queue_id in the
directory dir. The command is terminated with a newline. The server must write a
newline-terminated "ok" if the scan completed successfully, or "error: msg" if
something went wrong.
relayok ip_addr hostname client_port daemon_ip daemon_port
Test whether or not to accept a connection from the specified host. The server
must write "ok 1" if we will accept the connection, or "ok 0 error_message code
dsn" if not. It can indicate a temporary failure by writing "ok -1 error_message
code dsn". Note that even if the connection is accepted, a later scan can still
reject the message based on other criteria. "ip_addr" is the IP address of the
relay and "hostname" is the hostname (if it could be determined; otherwise, the IP
address in square brackets).
helook ip_addr hostname helo_string client_port daemon_ip daemon_port
Test whether or not to accept the HELO/EHLO command. The server must write "ok 1"
if we will accept the mail attempt, or "ok 0 error_message code dsn" if not. "ok
-1 error_message code dsn" indicates a temporary failure. helo_string is the
argument to the HELO/EHLO command. The remaining arguments have the same meaning
as in relayok.
senderok sender_addr ip_addr hostname helo_string dir queue_id [esmtp_args...]
Test whether or not to accept mail from the specified sender. The server must
write "ok 1" if we will accept the mail attempt, or "ok 0 error_message code dsn"
if not. "ok -1 error_message code dsn" indicates a temporary failure. Note that
even if the sender is accepted, a later scan can still reject the message based on
other criteria. "sender_addr" is the sender's e-mail address. The "ip_addr" and
"hostname" arguments are as in relayok. "helo_string" is the argument to the SMTP
HELO/EHLO command. "dir" is the MIMEDefang spool directory, and "queue_id" is the
Sendmail queue identifier.
The optional "esmtp_args" are space-separated, percent-encoded ESMTP arguments
supplied with the MAIL FROM: command.
recipok recip_addr sender_addr ip_addr hostname first_recip helo_string dir queue_id
[esmtp_args...]
Test whether or not to accept mail for the specified recipient. The server must
write "ok 1" if we will accept it, or "ok 0 error_message code dsn" if not. ok -1
error_message code dsn" indicates a temporary-failure.
"recip_addr" is the argument to the RCPT TO: command, and "first_recip" is the
argument to the first RCPT TO: command for this message. Other arguments are as in
senderok.
map map_name key
If you are using a map socket (the -N option to mimedefang-multiplexor), then the
server should look up the key key in the map map_name. The server should print a
single line to standard output. The first word on the line should be one of OK,
NOTFOUND, TEMP, TIMEOUT or PERM, indicating a successful lookup, absence of the
key, a temporary failure, a timeout or a permanent failure, respectively. This
should be followed by a space and a percent-encoded string representing the value
of the key (if it was found) or an optional error message (if something went
wrong.)
tick band
The filter should run filter_tick with the specified band argument. It should
print a single line to standard output:
tock band
Additional Commands
The filter can define a function filter_unknown_cmd that can extend the list of
server commands. If you do this, make sure all of your commands start with an
upper-case letter to avoid conflicts if more built-in commands are defined in the
future.
SERVER REPLIES
The reply codes are:
ok [return_code] [parameters]
The operation completed successfully. Some operations have an associated return
code, and possibly other parameters as well. See the source code for the gory
details.
error: Message
The operation failed. Message may give additional details.
In server mode, you should not write anything to standard output except reply codes, or
the multiplexor will become confused. You should not terminate the program in server
mode; simply echo an error: reply and return to the server loop.
When you send a reply code back to the multiplexor, be sure to terminate it with a
newline, and to flush standard output. If your program uses the Standard I/O library,
standard output may not be flushed immediately, and mimedefang-multiplexor will wait
forever for the filter's reply, and eventually kill the filter on the assumption it has
hung up.
In server mode, if the filter program receives a SIGINT signal, it must terminate. This
is used by mimedefang-multiplexor to terminate slaves after they have processed a given
number of e-mail messages.
AUTHOR
mimedefang was written by David F. Skoll <dfs@roaringpenguin.com>. The mimedefang home
page is http://www.mimedefang.org/.
SEE ALSO
mimedefang.pl(8), mimedefang(8), mimedefang-multiplexor(8), mimedefang-filter(5)