140266059SGregory Neil Shapiro<html> 240266059SGregory Neil Shapiro<head> 340266059SGregory Neil Shapiro<title>Architecture</title> 440266059SGregory Neil Shapiro</head> 540266059SGregory Neil Shapiro<body> 640266059SGregory Neil Shapiro 740266059SGregory Neil Shapiro<h1>Architecture</h1> 840266059SGregory Neil Shapiro 940266059SGregory Neil Shapiro<h2>Contents</h2> 1040266059SGregory Neil Shapiro 1140266059SGregory Neil Shapiro<ul> 1240266059SGregory Neil Shapiro <li>Design Goals 1340266059SGregory Neil Shapiro <li>Implementing Filtering Policies 1440266059SGregory Neil Shapiro <li>MTA - Filter Communication 1540266059SGregory Neil Shapiro</ul> 1640266059SGregory Neil Shapiro 1740266059SGregory Neil Shapiro<h2>Goals</h2> 1840266059SGregory Neil Shapiro 1940266059SGregory Neil ShapiroThe Sendmail Content Management API (Milter) provides an interface for 2040266059SGregory Neil Shapirothird-party software to validate and modify messages as they pass 2140266059SGregory Neil Shapirothrough the mail transport system. Filters can process messages' 2240266059SGregory Neil Shapiroconnection (IP) information, envelope protocol elements, message 2340266059SGregory Neil Shapiroheaders, and/or message body contents, and modify a message's 2440266059SGregory Neil Shapirorecipients, headers, and body. The MTA configuration file specifies 2540266059SGregory Neil Shapirowhich filters are to be applied, and in what order, allowing an 2640266059SGregory Neil Shapiroadministrator to combine multiple independently-developed filters. 2740266059SGregory Neil Shapiro 2840266059SGregory Neil Shapiro<p> 2940266059SGregory Neil ShapiroWe expect to see both vendor-supplied, configurable mail filtering 3040266059SGregory Neil Shapiroapplications and a multiplicity of script-like filters designed by and 3140266059SGregory Neil Shapirofor MTA administrators. A certain degree of coding sophistication and 3240266059SGregory Neil Shapirodomain knowledge on the part of the filter provider is assumed. This 3340266059SGregory Neil Shapiroallows filters to exercise fine-grained control at the SMTP level. 3440266059SGregory Neil ShapiroHowever, as will be seen in the example, many filtering applications 3540266059SGregory Neil Shapirocan be written with relatively little protocol knowledge. 3640266059SGregory Neil Shapiro 3740266059SGregory Neil Shapiro<p> 3840266059SGregory Neil ShapiroGiven these expectations, the API is designed to achieve the following 3940266059SGregory Neil Shapirogoals: 4040266059SGregory Neil Shapiro 4140266059SGregory Neil Shapiro<OL> 4240266059SGregory Neil Shapiro <LI>Safety/security. 4340266059SGregory Neil Shapiro Filter processes should not need to run as root 4440266059SGregory Neil Shapiro (of course, they can if required, but that is a local issue); 4540266059SGregory Neil Shapiro this will simplify coding 4640266059SGregory Neil Shapiro and limit the impact of security flaws in the filter program. 4740266059SGregory Neil Shapiro<p> 4840266059SGregory Neil Shapiro <LI>Reliability. 4940266059SGregory Neil Shapiro Coding failures in a Milter process that cause that process 5040266059SGregory Neil Shapiro to hang or core-dump 5140266059SGregory Neil Shapiro should not stop mail delivery. 5240266059SGregory Neil Shapiro Faced with such a failure, 5340266059SGregory Neil Shapiro sendmail should use a default mechanism, 5440266059SGregory Neil Shapiro either behaving as if the filter were not present 5540266059SGregory Neil Shapiro or as if a required resource were unavailable. 5640266059SGregory Neil Shapiro The latter failure mode will generally have sendmail return 5740266059SGregory Neil Shapiro a 4xx SMTP code (although in later phases of the SMTP protocol 5840266059SGregory Neil Shapiro it may cause the mail to be queued for later processing). 5940266059SGregory Neil Shapiro<p> 6040266059SGregory Neil Shapiro <LI>Simplicity. 6140266059SGregory Neil Shapiro The API should make implementation of a new filter 6240266059SGregory Neil Shapiro no more difficult than absolutely necessary. 6340266059SGregory Neil Shapiro Subgoals include: 6440266059SGregory Neil Shapiro <UL> 6540266059SGregory Neil Shapiro <LI>Encourage good thread practice 6640266059SGregory Neil Shapiro by defining thread-clean interfaces including local data hooks. 6740266059SGregory Neil Shapiro <LI>Provide all interfaces required 6840266059SGregory Neil Shapiro while avoiding unnecessary pedanticism. 6940266059SGregory Neil Shapiro </UL> 7040266059SGregory Neil Shapiro<p> 7140266059SGregory Neil Shapiro <LI>Performance. 7240266059SGregory Neil Shapiro Simple filters should not seriously impact overall MTA performance. 7340266059SGregory Neil Shapiro</OL> 7440266059SGregory Neil Shapiro 7540266059SGregory Neil Shapiro<h2>Implementing Filtering Policies</h2> 7640266059SGregory Neil Shapiro 7740266059SGregory Neil ShapiroMilter is designed to allow a server administrator to combine 7840266059SGregory Neil Shapirothird-party filters to implement a desired mail filtering policy. For 7940266059SGregory Neil Shapiroexample, if a site wished to scan incoming mail for viruses on several 8040266059SGregory Neil Shapiroplatforms, eliminate unsolicited commercial email, and append a mandated 8140266059SGregory Neil Shapirofooter to selected incoming messages, the administrator could configure 8240266059SGregory Neil Shapirothe MTA to filter messages first through a server based anti-virus 8340266059SGregory Neil Shapiroengine, then via a large-scale spam-catching service, and finally 8440266059SGregory Neil Shapiroappend the desired footer if the message still met requisite criteria. 8540266059SGregory Neil ShapiroAny of these filters could be added or changed independently. 8640266059SGregory Neil Shapiro 8740266059SGregory Neil Shapiro<p> 8840266059SGregory Neil ShapiroThus the site administrator, not the filter writer, controls the 8940266059SGregory Neil Shapirooverall mail filtering environment. In particular, he/she must decide 9040266059SGregory Neil Shapirowhich filters are run, in what order they are run, and how they 9140266059SGregory Neil Shapirocommunicate with the MTA. These parameters, as well as the 9240266059SGregory Neil Shapiroactions to be taken if a filter becomes unavailable, are selectable 9340266059SGregory Neil Shapiroduring MTA configuration. <a href="installation.html">Further 9440266059SGregory Neil Shapirodetails</a> are available later in this document. 9540266059SGregory Neil Shapiro 9640266059SGregory Neil Shapiro<h2>MTA - Filter communication</h2> 9740266059SGregory Neil Shapiro 9840266059SGregory Neil ShapiroFilters run as separate processes, outside of the sendmail address 9940266059SGregory Neil Shapirospace. The benefits of this are threefold: 10040266059SGregory Neil Shapiro 10140266059SGregory Neil Shapiro<OL> 10240266059SGregory Neil Shapiro <LI>The filter need not run with "root" permissions, thereby 10340266059SGregory Neil Shapiro avoiding a large family of potential security problems.</LI> 10440266059SGregory Neil Shapiro 10540266059SGregory Neil Shapiro <LI>Failures in a particular filter will not affect the MTA or 10640266059SGregory Neil Shapiro other filters.</LI> 10740266059SGregory Neil Shapiro 10840266059SGregory Neil Shapiro <LI>The filter can potentially have higher performance because of 10940266059SGregory Neil Shapiro the parallelism inherent in multiple processes.</LI> 11040266059SGregory Neil Shapiro</OL> 11140266059SGregory Neil Shapiro 11240266059SGregory Neil Shapiro<p> 11340266059SGregory Neil ShapiroEach filter may communicate with multiple MTAs at the same time over 11440266059SGregory Neil Shapirolocal or remote connections, using multiple threads of execution. <a 11540266059SGregory Neil Shapirohref="#figure-1">Figure 1</a> illustrates a possible network of 11640266059SGregory Neil Shapirocommunication channels between a site's filters, its MTAs, and other 11740266059SGregory Neil ShapiroMTAs on the network: 11840266059SGregory Neil Shapiro</p> 11940266059SGregory Neil Shapiro<div align="center"> 12040266059SGregory Neil Shapiro<a name="figure-1"><img src="figure1.jpg" ALT=""></A><br> 12140266059SGregory Neil Shapiro<b>Figure 1: A set of MTA's interacting with a set of filters.</b> 12240266059SGregory Neil Shapiro</div> 12340266059SGregory Neil Shapiro<p> 12440266059SGregory Neil ShapiroThe Milter library (libmilter) implements the communication protocol. 12540266059SGregory Neil ShapiroIt accepts connections from various MTAs, passes the relevant data to 12640266059SGregory Neil Shapirothe filter through callbacks, then makes appropriate responses based 12740266059SGregory Neil Shapiroon return codes. A filter may also send data to the MTA as a result 12840266059SGregory Neil Shapiroof library calls. <a href="#figure-2">Figure 2</a> shows a single 12940266059SGregory Neil Shapirofilter process processing messages from two MTAs: 13040266059SGregory Neil Shapiro</p> 13140266059SGregory Neil Shapiro<div align="center"> 13240266059SGregory Neil Shapiro<img src="figure2.jpg" ALT=""><br> 13340266059SGregory Neil Shapiro<b>Figure 2: A filter handling simultaneous requests from two MTA's.</b> 13440266059SGregory Neil Shapiro</div> 13540266059SGregory Neil Shapiro<hr size="1"> 13640266059SGregory Neil Shapiro<font size="-1"> 13740266059SGregory Neil ShapiroCopyright (c) 2000 Sendmail, Inc. and its suppliers. 13840266059SGregory Neil ShapiroAll rights reserved. 13940266059SGregory Neil Shapiro<br> 14040266059SGregory Neil ShapiroBy using this file, you agree to the terms and conditions set 14140266059SGregory Neil Shapiroforth in the <a href="LICENSE.txt">LICENSE</a>. 14240266059SGregory Neil Shapiro</font> 14340266059SGregory Neil Shapiro</body> 14440266059SGregory Neil Shapiro</html> 145
