Sun Java System Messaging Server 6.3 Administration Guide

14.8 Using Milter

This section consists of the following subsections: 14.8 Using Milter

14.8.1 Milter Overview

Milter is the short name for Sendmail Content Management API. It also refers to software written using this API. Milter provides a plug-in interface for third-party software to validate, modify, or block messages as they pass through the MTA. Milters can process a message's connection (IP) information, envelope protocol elements, message headers, and/or message body contents, and modify a message's recipients, headers, and body. Possible uses for filters include spam rejection, virus filtering, and content control. In general, Milter seeks to address site-wide filtering concerns in a scalable way. Originally designed for sendmail, Milters written for sendmail can now be used with Messaging Server, although some limitations may apply (see below). For more information on Milter refer to the Internet.

14.8.2 Milter/Messaging Server Theory of Operations

Milters control what action is to be performed on a message. Messaging Server controls what messages are to be acted upon by a Milter using the methods described in 14.2.2 Specifying the Messages to Be Filtered.

In sendmail, Milter consists of support code in sendmail itself and a separate libmilter library. Filter authors link their filters against libmilter to produce a server. Sendmail is then configured to connect to these Milter servers.

Messaging Server provides a library that emulates the sendmail side of the Milter interface. This allows Milters written for sendmail to be used with Messaging Server.

A few words of caution are in order here. The Milter protocol consists of a complex mixture of text and binary elements and is not well documented. Additionally, Milter semantics are tightly coupled with sendmail's way of processing messages. In particular, Milters can and usually do access a subset of the macros defined in the sendmail configuration. Messaging Server's Milter client library attempts to provide a reasonable set of sendmail macros, but it is entirely possible for a Milter to be written that depends on a specific aspect of sendmail configuration which is not currently implemented. The net result is that an arbitrary Milter pulled off the network may or may not work with this client library. If problems develop we'll try and resolve them, but we cannot possibly guarantee success with every Milter out there.

14.8.3 Milter Requirements and Usage Considerations

The Milter server can run on a separate system of its own, on the same system as Messaging Server, in a single system deployment, or, in a two-tier deployment, on the same system as the MTA. When LMTP is used between the MTA and the message store, the filtering must be invoked from the MTA, it can not be invoked from the message store. When SMTP is used between the MTA and the message store it can be invoked from either one, and it can run on either system or a third separate system.

Messaging Server supports connecting to multiple Milter servers. If you specify a domain name that translates to multiple IP addresses, the system will try all of them in order received from the DNS until one works. Some DNS servers support randomizing the order of addresses they return, so this provides a primitive load balancing/failover facility.

14.8.3.1 Supported Milter Message Modification Actions

The Milter interface currently supports the ability to add headers (SMFIF_ADDHDRS), change or delete headers (SMFIF_CHGHDRS), and quarantine messages (SMFIF_QUARANTINE). Changing the message body (SMFIF_CHGBODY), adding recipients (SMFIF_ADDRCPT) and deleting recipients (SMFIF_DELRCPT) are not supported at the present time.

14.8.3.2 Macros Provided by the Milter Interface

The following macros are currently defined by the Milter interface:

$j Text placed in the by clause of Received: header fields. In Messaging Server this is controlled by the RECEIVED_DOMAIN MTA option. If the option is not set, the official host on the local channel is used instead.

${client_addr} The IP address of the SMTP client, expressed as a dotted quad value. Only set when SMTP over TCP is being used.

$i Queue ID for the current message. Messaging Server generates a unique ID for each session; this ID is what appears in the $i macro.

${mail_addr} The MAIL FROM address for the current transaction.

${mail_host} The host part of the MAIL FROM address for the current transaction.

${rcpt_addr} A RCPT TO address for the current transaction.

${rcpt_host} The host part of the current RCPT TO address.

To Deploy Milter

Perform the following steps to deploy Milter.

Obtain and configure a Milter that will perform the actions you desire.

Refer to specific Milter documentation for obtaining and configuring information.

Load and configure the Milter client library. (See 14.2.1 Loading and Configuring the Spam Filtering Software Client Library.)
1. Specify the path to the client library, libmilter.so. Specify the path and name of the Milter configuration file.
  
  Example:
  spamfilter1_library=/opt/SUNWmsgsr/lib/libmilter.so spamfilter1_config_file=/opt/SUNWmsgsr/lib/milter.opt
2. Create a Milter configuration file. with the desired options.
  
  The Milter option file consists of lines of the form option=value. The two required options are HOST and PORT. HOST must be set to the name of the system where the Milter server is running while PORT must be set to the port the Milter server is configured to listen on. Note that only TCP/IP connections are supported; UNIX domain sockets cannot be specified or used.
  
  Several additional options are also available in this options file:
  
  DEBUG (integer, default 0) — Enables or disables debug output from the Milter client library. The larger the value, the more debugging output will be produced. 0 produces no output. 1 provides basic debugging. 2 adds logging of TCP traffic. (Debug output from the Milter server is typically controlled by a setting on the command line used to start the server. Note that most Milters seem to only provide the ability to direct debug output to syslog.)
  
  TIMEOUT (integer, default 3600) — Specifies the timeout in hundredths of seconds for operations involving the Milter connection. Available in 6.3 and later versions.
  
  SOCKS_HOST (string, default "") — Specifies the name of an intermediate SOCKS server. If this option is specified the Milter connection is made through the specified SOCKS server and not directly.
  
  SOCKS_PORT (integer, default 1080) — Specifies the port the intermediate SOCKS server is running on.
  
  SOCKS_PASSWORD (string, default "") — Specifies a password to use in establishing the connection through the SOCKS server. Whether or not a username/password is required depends on the SOCKS server configuration.

Specify what messages to send to Milter.

Messages can be filtered by user, domain, or channel. See 14.2.2 Specifying the Messages to Be Filtered.

Set the spamfilterX_string_action option in the option.dat file:

spamfilterX_string_action=data:,$M

This setting is used unconditionally, but must be in the MTA options file for Milter to work properly.