design.html revision 90792
190792Sgshapiro<html> 290792Sgshapiro<head> 390792Sgshapiro<title>Architecture</title> 490792Sgshapiro</head> 590792Sgshapiro<body> 690792Sgshapiro 790792Sgshapiro<h1>Architecture</h1> 890792Sgshapiro 990792Sgshapiro<h2>Contents</h2> 1090792Sgshapiro 1190792Sgshapiro<ul> 1290792Sgshapiro <li>Design Goals 1390792Sgshapiro <li>Implementing Filtering Policies 1490792Sgshapiro <li>MTA - Filter Communication 1590792Sgshapiro</ul> 1690792Sgshapiro 1790792Sgshapiro<h2>Goals</h2> 1890792Sgshapiro 1990792SgshapiroThe Sendmail Content Management API (Milter) provides an interface for 2090792Sgshapirothird-party software to validate and modify messages as they pass 2190792Sgshapirothrough the mail transport system. Filters can process messages' 2290792Sgshapiroconnection (IP) information, envelope protocol elements, message 2390792Sgshapiroheaders, and/or message body contents, and modify a message's 2490792Sgshapirorecipients, headers, and body. The MTA configuration file specifies 2590792Sgshapirowhich filters are to be applied, and in what order, allowing an 2690792Sgshapiroadministrator to combine multiple independently-developed filters. 2790792Sgshapiro 2890792Sgshapiro<p> 2990792SgshapiroWe expect to see both vendor-supplied, configurable mail filtering 3090792Sgshapiroapplications and a multiplicity of script-like filters designed by and 3190792Sgshapirofor MTA administrators. A certain degree of coding sophistication and 3290792Sgshapirodomain knowledge on the part of the filter provider is assumed. This 3390792Sgshapiroallows filters to exercise fine-grained control at the SMTP level. 3490792SgshapiroHowever, as will be seen in the example, many filtering applications 3590792Sgshapirocan be written with relatively little protocol knowledge. 3690792Sgshapiro 3790792Sgshapiro<p> 3890792SgshapiroGiven these expectations, the API is designed to achieve the following 3990792Sgshapirogoals: 4090792Sgshapiro 4190792Sgshapiro<OL> 4290792Sgshapiro <LI>Safety/security. 4390792Sgshapiro Filter processes should not need to run as root 4490792Sgshapiro (of course, they can if required, but that is a local issue); 4590792Sgshapiro this will simplify coding 4690792Sgshapiro and limit the impact of security flaws in the filter program. 4790792Sgshapiro<p> 4890792Sgshapiro <LI>Reliability. 4990792Sgshapiro Coding failures in a Milter process that cause that process 5090792Sgshapiro to hang or core-dump 5190792Sgshapiro should not stop mail delivery. 5290792Sgshapiro Faced with such a failure, 5390792Sgshapiro sendmail should use a default mechanism, 5490792Sgshapiro either behaving as if the filter were not present 5590792Sgshapiro or as if a required resource were unavailable. 5690792Sgshapiro The latter failure mode will generally have sendmail return 5790792Sgshapiro a 4xx SMTP code (although in later phases of the SMTP protocol 5890792Sgshapiro it may cause the mail to be queued for later processing). 5990792Sgshapiro<p> 6090792Sgshapiro <LI>Simplicity. 6190792Sgshapiro The API should make implementation of a new filter 6290792Sgshapiro no more difficult than absolutely necessary. 6390792Sgshapiro Subgoals include: 6490792Sgshapiro <UL> 6590792Sgshapiro <LI>Encourage good thread practice 6690792Sgshapiro by defining thread-clean interfaces including local data hooks. 6790792Sgshapiro <LI>Provide all interfaces required 6890792Sgshapiro while avoiding unnecessary pedanticism. 6990792Sgshapiro </UL> 7090792Sgshapiro<p> 7190792Sgshapiro <LI>Performance. 7290792Sgshapiro Simple filters should not seriously impact overall MTA performance. 7390792Sgshapiro</OL> 7490792Sgshapiro 7590792Sgshapiro<h2>Implementing Filtering Policies</h2> 7690792Sgshapiro 7790792SgshapiroMilter is designed to allow a server administrator to combine 7890792Sgshapirothird-party filters to implement a desired mail filtering policy. For 7990792Sgshapiroexample, if a site wished to scan incoming mail for viruses on several 8090792Sgshapiroplatforms, eliminate unsolicited commercial email, and append a mandated 8190792Sgshapirofooter to selected incoming messages, the administrator could configure 8290792Sgshapirothe MTA to filter messages first through a server based anti-virus 8390792Sgshapiroengine, then via a large-scale spam-catching service, and finally 8490792Sgshapiroappend the desired footer if the message still met requisite criteria. 8590792SgshapiroAny of these filters could be added or changed independently. 8690792Sgshapiro 8790792Sgshapiro<p> 8890792SgshapiroThus the site administrator, not the filter writer, controls the 8990792Sgshapirooverall mail filtering environment. In particular, he/she must decide 9090792Sgshapirowhich filters are run, in what order they are run, and how they 9190792Sgshapirocommunicate with the MTA. These parameters, as well as the 9290792Sgshapiroactions to be taken if a filter becomes unavailable, are selectable 9390792Sgshapiroduring MTA configuration. <a href="installation.html">Further 9490792Sgshapirodetails</a> are available later in this document. 9590792Sgshapiro 9690792Sgshapiro<h2>MTA - Filter communication</h2> 9790792Sgshapiro 9890792SgshapiroFilters run as separate processes, outside of the sendmail address 9990792Sgshapirospace. The benefits of this are threefold: 10090792Sgshapiro 10190792Sgshapiro<OL> 10290792Sgshapiro <LI>The filter need not run with "root" permissions, thereby 10390792Sgshapiro avoiding a large family of potential security problems.</LI> 10490792Sgshapiro 10590792Sgshapiro <LI>Failures in a particular filter will not affect the MTA or 10690792Sgshapiro other filters.</LI> 10790792Sgshapiro 10890792Sgshapiro <LI>The filter can potentially have higher performance because of 10990792Sgshapiro the parallelism inherent in multiple processes.</LI> 11090792Sgshapiro</OL> 11190792Sgshapiro 11290792Sgshapiro<p> 11390792SgshapiroEach filter may communicate with multiple MTAs at the same time over 11490792Sgshapirolocal or remote connections, using multiple threads of execution. <a 11590792Sgshapirohref="#figure-1">Figure 1</a> illustrates a possible network of 11690792Sgshapirocommunication channels between a site's filters, its MTAs, and other 11790792SgshapiroMTAs on the network: 11890792Sgshapiro</p> 11990792Sgshapiro<div align="center"> 12090792Sgshapiro<a name="figure-1"><img src="figure1.jpg" ALT=""></A><br> 12190792Sgshapiro<b>Figure 1: A set of MTA's interacting with a set of filters.</b> 12290792Sgshapiro</div> 12390792Sgshapiro<p> 12490792SgshapiroThe Milter library (libmilter) implements the communication protocol. 12590792SgshapiroIt accepts connections from various MTAs, passes the relevant data to 12690792Sgshapirothe filter through callbacks, then makes appropriate responses based 12790792Sgshapiroon return codes. A filter may also send data to the MTA as a result 12890792Sgshapiroof library calls. <a href="#figure-2">Figure 2</a> shows a single 12990792Sgshapirofilter process processing messages from two MTAs: 13090792Sgshapiro</p> 13190792Sgshapiro<div align="center"> 13290792Sgshapiro<img src="figure2.jpg" ALT=""><br> 13390792Sgshapiro<b>Figure 2: A filter handling simultaneous requests from two MTA's.</b> 13490792Sgshapiro</div> 13590792Sgshapiro<hr size="1"> 13690792Sgshapiro<font size="-1"> 13790792SgshapiroCopyright (c) 2000 Sendmail, Inc. and its suppliers. 13890792SgshapiroAll rights reserved. 13990792Sgshapiro<br> 14090792SgshapiroBy using this file, you agree to the terms and conditions set 14190792Sgshapiroforth in the <a href="LICENSE.txt">LICENSE</a>. 14290792Sgshapiro</font> 14390792Sgshapiro</body> 14490792Sgshapiro</html> 145
