About milter plugin
From MsgServerDocWiki
What is the milter plugin and how do I use it?
UPDATE, 9/13/2010: This information has been moved to http://wikis.sun.com/display/CommSuite/About+the+Milter+Plugin. Refer to that page from now on.
Contents |
[edit] Milter plugin overview
Sun Messaging Server has introduced a milter-client plugin to extend its existing mail filtering and modification capability. This plug-in, which is provided by default in Messaging Server 6.3, allows messaging server to communicate with 3rd part milter servers using the de-facto milter protocol.
This document goes through the compilation of milter servers using the milter-API provided by sendmail, integration with messaging server and debugging milter protocol communication between the milter server and the milter client (messaging server).
incoming email -> milter client plugin (Sun Messaging Server MTA) -> outgoing modified/rejected email action
^
| (Milter Protocol)
V
milter server
Diagram: milter plugin interaction
The milter server can return different actions responses:
- Reject an email on a per-recipient or message basis
- Reject an email with a specific return code/message
- Accept email for processing
- Add additional recipient(s)
- Remove recipient(s)
- Quarantine (hold) message
The milter server can also return responses to modify the contents of a message in a number of ways including:
- Replace the body contents
- Modify, delete or add email headers
All the above actions are supported (as of 120228-20/120229-20/120230-20/126479-01/126480-01 messaging server patch) by the Messaging Server milter client and provide increased flexibility for Messaging Server MTA's on the processing of emails.
Further details on the milter plugin can be found in Chapter 14.8 Using Milter of the Sun Java System Messaging Server 6.3 Administration Guide
[edit] History of Sun Messaging Server milter plugin
| Patch level | Functionality offered/modified/fixed |
|---|---|
| 120228-15 | Initial release of messaging server containing milter plugin |
| 120228-20/126479-01 | Added support for addition and deletion of recipients |
| 120228-22/126479-03 | Added additional macros {source_channel} {destination_channel} (6564907) |
| MS 7.0 | Added {optin} macro to provide the milter server the spam filter optin value at the RCPT TO processing stage. |
| MS 7u2 (patch -07) | Added USE_JETTISON option to control behaviour of milter discard action. |
Substitute 120229 (32 bit)/126480 (64bit) for Solaris 10 x86 and 120230 for Linux releases of Messaging Server 6.3
[edit] Known limitations & differences to Sendmail behaviour
The milter protocol was originally written for and used by Sendmail. The Sendmail MTA acts as a milter client in the same fashion as Sun Messaging Server but due to underlying design and conceptual differences between the two products the behaviour based on milter server responses may vary.
Ability to use milters on a per-recipient basis
Sendmail milter client filtering by default applies to all email recipients of any given email. Sun messaging server on the other hand allows you to specify whether an email is filtered or not based on a number of possibilities (e.g. channels, opt-in attribute). Therefore a single email may be destined to multiple recipients, some of which are filtered and some of which that are not. This means that Sun Messaging Server is more flexible in its filter but this can have other consequences such as not being able to reject at the connect, or mail from stages of SMTP delivery.
Sun Messaging server ignores the reply code for rejection actions
The reply code is ignored because it is completely inappropriate to allow setting of arbitrary reply code values in SMTP. The set of available values is quite restricted, there are clients out there that misbehave when presented with undefined codes, and there are few if any cases where the code returned should vary depending on why the milter decided to return an error condition.
The Extended reply codes, on the other hand, are designed to convey the sort of error information you'd want this sort of processing to present to the remote client. Therefore these are passed through.
Sun Messaging server doesn't provide certain macros
Like the Postfix MTA which also has the ability to filter based on milter server results, Sun messaging server doesn't provide the "{if_addr}" macro. Use the "{client_addr}" macro instead.
Sun Messaging server doesn't allow explicit definition of multi-line headers
As per the milter API for addheader/changeheader:
"If longer headers are needed, make them multi-line. To make a multi-line header, insert a line feed (ASCII 0x0a, or \n in C) followed by at least one whitespace character such as a space (ASCII 0x20) or tab (ASCII 0x09, or \t in C)."
Due to the way that messaging server represents headers internally, for efficiency sake we don't allow the explicit construction of multi-line headers which therefore means we strip out CRLFs from any line that comes from the milter interface unconditionally. Therefore if you attempt to specify a multi-line header, it will be converted into a longer single-line header.
Sun Messaging server only supports the 8.13.X milter protocol (not 8.14.X)
At this time Sun Messaging server only supports the 8.13.X milter API/protocol. There is no timeline at this stage for the support the new actions/protocol provided by the 8.14.X API/protocol.
[edit] Milter Servers tested with Sun Messaging Server
- milter-greylist
- MIMEDefang
- clamav-milter
- Sophos PureMessage
- OpenDKIM
- SpamAssassin
If you have had success or failures/problems with other milter servers, please provide feedback so we can update this document.
A more extensive list of both commercial and open-source milter servers can be found at the following links:
[edit] Getting started with milter
Processing of emails using the milter protocol requires two components; the milter client (Messaging Server 6.3 or above) and a milter server.
[edit] Milter Server
There are a number of milter servers already written to provide a wide array of functionality including greylisting, MIME part modification, virus scanning, spam filter (refer above). The Sendmail milter library commonly used to compile milter servers can be configured to listen on either a Unix socket or a TCP port. The Messaging Server 6.3 milter plug-in doesn't support the Unix socket mechanism.
The milter-server can run on the same host as the Messaging Server instance or on any other network (TCP/IP) connected system.
Although these steps will change on a per-milter-server basis, the meta tasks to getting a milter-server running are as follows:
1. Download the Sendmail source code & compile the libmilter Sendmail library (if one doesn't already exist on the system) 2. Compile the milter-server (a simple sample-milter is available at the Sendmail milter site) 3. Run the milter-server, configure it to run on the INET:<TCP port number> socket.
[edit] Milter Client
The configuration of the milter-client component involves configuring the milter-client plug-in to Messaging Server. This is documented in the Messaging Server Administrator 6.3 Guide
[edit] Debugging & troubleshooting milter plugin
Before attempting to debug the milter plugin, you should be using at a minimum 120228-20/126479-01 patch level for messaging server. This patch contains a large number of fixes.
Debugging the milter interface can be achieved by setting the DEBUG option in the Messaging Server milter-plugin option file.
DEBUG=1 -> Basic debugging DEBUG=2 -> In depth debugging including packet level tracing.
A breakdown of the network-level milter protocol (8.12) is available here and is suitable for diagnosing issues with the data provided by the milter-server (or client):
http://search.cpan.org/src/AVAR/Sendmail-PMilter-0.96/doc/milter-protocol.txt
Please make sure that the data provided by the milter-server confirms to the milter-API document
[edit] Known Errors
Sep 26 09:24:46 reboot mimedefang[21017]: [ID 752427 mail.error] MIMEDefang-2.57: st_optionneg[3]: 0x33 does not fulfill action requirements 0x3f
If you see the above error or something similar, this indicates that the milter client (messaging server) didn't have the required functionality. Make sure that the milter server you are using is compatible with 8.13.X of Sendmail and that you are using 120228-20/126479-01 patch level or above for messaging server.
[edit] Milter server development hints/tips
The way that the messaging server milter client plugin operates and the overall design of Sun messaging server means that the behaviour will differ to that of Sendmail.
For example if you enable a milter plugin based on the recipients destination channel (e.g. destinationspam1optin spam) then the milter won't get called until the RCPT TO: phase (since the destination channel cannot be determined until this point). So if your milter server rejects at the 'connect' stage, this won't be reflected by messaging server (it will reject much later in the SMTP conversation).
Categories: FAQ | MTA
