1168515Sgshapiro<HTML> 2168515Sgshapiro<HEAD> 3168515Sgshapiro<TITLE>Architecture</TITLE> 4168515Sgshapiro</HEAD> 5168515Sgshapiro<BODY> 6132943Sgshapiro<!-- 7168515Sgshapiro$Id: design.html,v 1.12 2006/08/08 20:55:57 ca Exp $ 8132943Sgshapiro--> 990792Sgshapiro 10168515Sgshapiro<H1>Architecture</H1> 1190792Sgshapiro 12168515Sgshapiro<H2>Contents</H2> 1390792Sgshapiro 14168515Sgshapiro<UL> 15168515Sgshapiro <LI>Design Goals 16168515Sgshapiro <LI>Implementing Filtering Policies 17168515Sgshapiro <LI>MTA - Filter Communication 18168515Sgshapiro</UL> 1990792Sgshapiro 20168515Sgshapiro<H2>Goals</H2> 2190792Sgshapiro 2290792SgshapiroThe Sendmail Content Management API (Milter) provides an interface for 2390792Sgshapirothird-party software to validate and modify messages as they pass 2490792Sgshapirothrough the mail transport system. Filters can process messages' 2590792Sgshapiroconnection (IP) information, envelope protocol elements, message 2690792Sgshapiroheaders, and/or message body contents, and modify a message's 2790792Sgshapirorecipients, headers, and body. The MTA configuration file specifies 2890792Sgshapirowhich filters are to be applied, and in what order, allowing an 2990792Sgshapiroadministrator to combine multiple independently-developed filters. 3090792Sgshapiro 31168515Sgshapiro<P> 3290792SgshapiroWe expect to see both vendor-supplied, configurable mail filtering 3390792Sgshapiroapplications and a multiplicity of script-like filters designed by and 3490792Sgshapirofor MTA administrators. A certain degree of coding sophistication and 3590792Sgshapirodomain knowledge on the part of the filter provider is assumed. This 3690792Sgshapiroallows filters to exercise fine-grained control at the SMTP level. 3790792SgshapiroHowever, as will be seen in the example, many filtering applications 3890792Sgshapirocan be written with relatively little protocol knowledge. 3990792Sgshapiro 40168515Sgshapiro<P> 4190792SgshapiroGiven these expectations, the API is designed to achieve the following 4290792Sgshapirogoals: 4390792Sgshapiro 4490792Sgshapiro<OL> 4590792Sgshapiro <LI>Safety/security. 4690792Sgshapiro Filter processes should not need to run as root 4790792Sgshapiro (of course, they can if required, but that is a local issue); 4890792Sgshapiro this will simplify coding 4990792Sgshapiro and limit the impact of security flaws in the filter program. 50168515Sgshapiro<P> 5190792Sgshapiro <LI>Reliability. 5290792Sgshapiro Coding failures in a Milter process that cause that process 5390792Sgshapiro to hang or core-dump 5490792Sgshapiro should not stop mail delivery. 5590792Sgshapiro Faced with such a failure, 5690792Sgshapiro sendmail should use a default mechanism, 5790792Sgshapiro either behaving as if the filter were not present 5890792Sgshapiro or as if a required resource were unavailable. 5990792Sgshapiro The latter failure mode will generally have sendmail return 6090792Sgshapiro a 4xx SMTP code (although in later phases of the SMTP protocol 6190792Sgshapiro it may cause the mail to be queued for later processing). 62168515Sgshapiro<P> 6390792Sgshapiro <LI>Simplicity. 6490792Sgshapiro The API should make implementation of a new filter 6590792Sgshapiro no more difficult than absolutely necessary. 6690792Sgshapiro Subgoals include: 6790792Sgshapiro <UL> 6890792Sgshapiro <LI>Encourage good thread practice 6990792Sgshapiro by defining thread-clean interfaces including local data hooks. 7090792Sgshapiro <LI>Provide all interfaces required 7190792Sgshapiro while avoiding unnecessary pedanticism. 7290792Sgshapiro </UL> 73168515Sgshapiro<P> 7490792Sgshapiro <LI>Performance. 7590792Sgshapiro Simple filters should not seriously impact overall MTA performance. 7690792Sgshapiro</OL> 7790792Sgshapiro 78168515Sgshapiro<H2>Implementing Filtering Policies</H2> 7990792Sgshapiro 8090792SgshapiroMilter is designed to allow a server administrator to combine 8190792Sgshapirothird-party filters to implement a desired mail filtering policy. For 8290792Sgshapiroexample, if a site wished to scan incoming mail for viruses on several 8390792Sgshapiroplatforms, eliminate unsolicited commercial email, and append a mandated 8490792Sgshapirofooter to selected incoming messages, the administrator could configure 8590792Sgshapirothe MTA to filter messages first through a server based anti-virus 8690792Sgshapiroengine, then via a large-scale spam-catching service, and finally 8790792Sgshapiroappend the desired footer if the message still met requisite criteria. 8890792SgshapiroAny of these filters could be added or changed independently. 8990792Sgshapiro 90168515Sgshapiro<P> 9190792SgshapiroThus the site administrator, not the filter writer, controls the 9290792Sgshapirooverall mail filtering environment. In particular, he/she must decide 9390792Sgshapirowhich filters are run, in what order they are run, and how they 9490792Sgshapirocommunicate with the MTA. These parameters, as well as the 9590792Sgshapiroactions to be taken if a filter becomes unavailable, are selectable 96168515Sgshapiroduring MTA configuration. <A href="installation.html">Further 97168515Sgshapirodetails</A> are available later in this document. 9890792Sgshapiro 99168515Sgshapiro<H2>MTA - Filter communication</H2> 10090792Sgshapiro 10190792SgshapiroFilters run as separate processes, outside of the sendmail address 10290792Sgshapirospace. The benefits of this are threefold: 10390792Sgshapiro 10490792Sgshapiro<OL> 10590792Sgshapiro <LI>The filter need not run with "root" permissions, thereby 10690792Sgshapiro avoiding a large family of potential security problems.</LI> 10790792Sgshapiro 10890792Sgshapiro <LI>Failures in a particular filter will not affect the MTA or 10990792Sgshapiro other filters.</LI> 11090792Sgshapiro 11190792Sgshapiro <LI>The filter can potentially have higher performance because of 11290792Sgshapiro the parallelism inherent in multiple processes.</LI> 11390792Sgshapiro</OL> 11490792Sgshapiro 115168515Sgshapiro<P> 11690792SgshapiroEach filter may communicate with multiple MTAs at the same time over 117168515Sgshapirolocal or remote connections, using multiple threads of execution. 118168515Sgshapiro<A HREF="#figure-1">Figure 1</A> illustrates a possible network of 11990792Sgshapirocommunication channels between a site's filters, its MTAs, and other 12090792SgshapiroMTAs on the network: 121168515Sgshapiro</P> 122168515Sgshapiro<DIV align="center"> 123168515Sgshapiro<A name="figure-1"><IMG src="figure1.jpg" ALT=""></A><BR> 124168515Sgshapiro<B>Figure 1: A set of MTA's interacting with a set of filters.</B> 125168515Sgshapiro</DIV> 126168515Sgshapiro<P> 12790792SgshapiroThe Milter library (libmilter) implements the communication protocol. 12890792SgshapiroIt accepts connections from various MTAs, passes the relevant data to 12990792Sgshapirothe filter through callbacks, then makes appropriate responses based 13090792Sgshapiroon return codes. A filter may also send data to the MTA as a result 131168515Sgshapiroof library calls. <A href="#figure-2">Figure 2</A> shows a single 13290792Sgshapirofilter process processing messages from two MTAs: 133168515Sgshapiro</P> 134168515Sgshapiro<DIV align="center"> 135168515Sgshapiro<IMG src="figure2.jpg" ALT=""><BR> 136168515Sgshapiro<B>Figure 2: A filter handling simultaneous requests from two MTA's.</B> 137168515Sgshapiro</DIV> 138168515Sgshapiro<HR size="1"> 139168515Sgshapiro<FONT size="-1"> 140112810SgshapiroCopyright (c) 2000, 2003 Sendmail, Inc. and its suppliers. 14190792SgshapiroAll rights reserved. 142168515Sgshapiro<BR> 14390792SgshapiroBy using this file, you agree to the terms and conditions set 144112810Sgshapiroforth in the LICENSE. 145168515Sgshapiro</FONT> 146168515Sgshapiro</BODY> 147168515Sgshapiro</HTML> 148
