MIMEDEFANG-PROTOCOL(7)

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 two 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.

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 escaped. 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.

Usubject
    The message subject.

Xmessage_id
    The Message-ID.

Rrecipient
    A recipient. There is one R line for each recipient.

!   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.

Hhost_name
    The SMTP relay host name.

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 importatnt 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:

Breply_text
    Bounce (reject) the message (with a 554 SMTP reply code) and the specified reply text.

D   Silently discard the message and pretend it was delivered.

Treply_text
    Return a 451 SMTP temporary failure code with the specified 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.

Uheader val
    Replace the value of 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.

Rrecip
    Add a new recipient recip to the message.

Srecip
    Delete recip from the list of message recipients.

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.

SERVER COMMANDS
    The commands defined are:

scan dir
    Run a scan 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
    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" if not. Note that even if the connection is accepted, a later scan can still reject the message based on other criteria

senderok email_addr
    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" if not. Note that even if the sender is accepted, a later scan can still reject the message based on other criteria

SERVER REPLIES
    The reply codes are:

ok [return_code]
    The operation completed successfully. Some operations have an associated return code.

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.roaringpenguin.com/mimedefang/.

SEE ALSO
mimedefang.pl(8), mimedefang(8), mimedefang-multiplexor(8)