1d0cef73dSGregory Neil Shapiro<HTML> 2d0cef73dSGregory Neil Shapiro<HEAD> 3d0cef73dSGregory Neil Shapiro<TITLE>Architecture</TITLE> 4d0cef73dSGregory Neil Shapiro</HEAD> 5d0cef73dSGregory Neil Shapiro<BODY> 6e92d3f3fSGregory Neil Shapiro<!-- 7*4313cc83SGregory Neil Shapiro$Id: design.html,v 1.13 2013-11-22 20:51:39 ca Exp $ 8e92d3f3fSGregory Neil Shapiro--> 940266059SGregory Neil Shapiro 10d0cef73dSGregory Neil Shapiro<H1>Architecture</H1> 1140266059SGregory Neil Shapiro 12d0cef73dSGregory Neil Shapiro<H2>Contents</H2> 1340266059SGregory Neil Shapiro 14d0cef73dSGregory Neil Shapiro<UL> 15d0cef73dSGregory Neil Shapiro <LI>Design Goals 16d0cef73dSGregory Neil Shapiro <LI>Implementing Filtering Policies 17d0cef73dSGregory Neil Shapiro <LI>MTA - Filter Communication 18d0cef73dSGregory Neil Shapiro</UL> 1940266059SGregory Neil Shapiro 20d0cef73dSGregory Neil Shapiro<H2>Goals</H2> 2140266059SGregory Neil Shapiro 2240266059SGregory Neil ShapiroThe Sendmail Content Management API (Milter) provides an interface for 2340266059SGregory Neil Shapirothird-party software to validate and modify messages as they pass 2440266059SGregory Neil Shapirothrough the mail transport system. Filters can process messages' 2540266059SGregory Neil Shapiroconnection (IP) information, envelope protocol elements, message 2640266059SGregory Neil Shapiroheaders, and/or message body contents, and modify a message's 2740266059SGregory Neil Shapirorecipients, headers, and body. The MTA configuration file specifies 2840266059SGregory Neil Shapirowhich filters are to be applied, and in what order, allowing an 2940266059SGregory Neil Shapiroadministrator to combine multiple independently-developed filters. 3040266059SGregory Neil Shapiro 31d0cef73dSGregory Neil Shapiro<P> 3240266059SGregory Neil ShapiroWe expect to see both vendor-supplied, configurable mail filtering 3340266059SGregory Neil Shapiroapplications and a multiplicity of script-like filters designed by and 3440266059SGregory Neil Shapirofor MTA administrators. A certain degree of coding sophistication and 3540266059SGregory Neil Shapirodomain knowledge on the part of the filter provider is assumed. This 3640266059SGregory Neil Shapiroallows filters to exercise fine-grained control at the SMTP level. 3740266059SGregory Neil ShapiroHowever, as will be seen in the example, many filtering applications 3840266059SGregory Neil Shapirocan be written with relatively little protocol knowledge. 3940266059SGregory Neil Shapiro 40d0cef73dSGregory Neil Shapiro<P> 4140266059SGregory Neil ShapiroGiven these expectations, the API is designed to achieve the following 4240266059SGregory Neil Shapirogoals: 4340266059SGregory Neil Shapiro 4440266059SGregory Neil Shapiro<OL> 4540266059SGregory Neil Shapiro <LI>Safety/security. 4640266059SGregory Neil Shapiro Filter processes should not need to run as root 4740266059SGregory Neil Shapiro (of course, they can if required, but that is a local issue); 4840266059SGregory Neil Shapiro this will simplify coding 4940266059SGregory Neil Shapiro and limit the impact of security flaws in the filter program. 50d0cef73dSGregory Neil Shapiro<P> 5140266059SGregory Neil Shapiro <LI>Reliability. 5240266059SGregory Neil Shapiro Coding failures in a Milter process that cause that process 5340266059SGregory Neil Shapiro to hang or core-dump 5440266059SGregory Neil Shapiro should not stop mail delivery. 5540266059SGregory Neil Shapiro Faced with such a failure, 5640266059SGregory Neil Shapiro sendmail should use a default mechanism, 5740266059SGregory Neil Shapiro either behaving as if the filter were not present 5840266059SGregory Neil Shapiro or as if a required resource were unavailable. 5940266059SGregory Neil Shapiro The latter failure mode will generally have sendmail return 6040266059SGregory Neil Shapiro a 4xx SMTP code (although in later phases of the SMTP protocol 6140266059SGregory Neil Shapiro it may cause the mail to be queued for later processing). 62d0cef73dSGregory Neil Shapiro<P> 6340266059SGregory Neil Shapiro <LI>Simplicity. 6440266059SGregory Neil Shapiro The API should make implementation of a new filter 6540266059SGregory Neil Shapiro no more difficult than absolutely necessary. 6640266059SGregory Neil Shapiro Subgoals include: 6740266059SGregory Neil Shapiro <UL> 6840266059SGregory Neil Shapiro <LI>Encourage good thread practice 6940266059SGregory Neil Shapiro by defining thread-clean interfaces including local data hooks. 7040266059SGregory Neil Shapiro <LI>Provide all interfaces required 7140266059SGregory Neil Shapiro while avoiding unnecessary pedanticism. 7240266059SGregory Neil Shapiro </UL> 73d0cef73dSGregory Neil Shapiro<P> 7440266059SGregory Neil Shapiro <LI>Performance. 7540266059SGregory Neil Shapiro Simple filters should not seriously impact overall MTA performance. 7640266059SGregory Neil Shapiro</OL> 7740266059SGregory Neil Shapiro 78d0cef73dSGregory Neil Shapiro<H2>Implementing Filtering Policies</H2> 7940266059SGregory Neil Shapiro 8040266059SGregory Neil ShapiroMilter is designed to allow a server administrator to combine 8140266059SGregory Neil Shapirothird-party filters to implement a desired mail filtering policy. For 8240266059SGregory Neil Shapiroexample, if a site wished to scan incoming mail for viruses on several 8340266059SGregory Neil Shapiroplatforms, eliminate unsolicited commercial email, and append a mandated 8440266059SGregory Neil Shapirofooter to selected incoming messages, the administrator could configure 8540266059SGregory Neil Shapirothe MTA to filter messages first through a server based anti-virus 8640266059SGregory Neil Shapiroengine, then via a large-scale spam-catching service, and finally 8740266059SGregory Neil Shapiroappend the desired footer if the message still met requisite criteria. 8840266059SGregory Neil ShapiroAny of these filters could be added or changed independently. 8940266059SGregory Neil Shapiro 90d0cef73dSGregory Neil Shapiro<P> 9140266059SGregory Neil ShapiroThus the site administrator, not the filter writer, controls the 9240266059SGregory Neil Shapirooverall mail filtering environment. In particular, he/she must decide 9340266059SGregory Neil Shapirowhich filters are run, in what order they are run, and how they 9440266059SGregory Neil Shapirocommunicate with the MTA. These parameters, as well as the 9540266059SGregory Neil Shapiroactions to be taken if a filter becomes unavailable, are selectable 96d0cef73dSGregory Neil Shapiroduring MTA configuration. <A href="installation.html">Further 97d0cef73dSGregory Neil Shapirodetails</A> are available later in this document. 9840266059SGregory Neil Shapiro 99d0cef73dSGregory Neil Shapiro<H2>MTA - Filter communication</H2> 10040266059SGregory Neil Shapiro 10140266059SGregory Neil ShapiroFilters run as separate processes, outside of the sendmail address 10240266059SGregory Neil Shapirospace. The benefits of this are threefold: 10340266059SGregory Neil Shapiro 10440266059SGregory Neil Shapiro<OL> 10540266059SGregory Neil Shapiro <LI>The filter need not run with "root" permissions, thereby 10640266059SGregory Neil Shapiro avoiding a large family of potential security problems.</LI> 10740266059SGregory Neil Shapiro 10840266059SGregory Neil Shapiro <LI>Failures in a particular filter will not affect the MTA or 10940266059SGregory Neil Shapiro other filters.</LI> 11040266059SGregory Neil Shapiro 11140266059SGregory Neil Shapiro <LI>The filter can potentially have higher performance because of 11240266059SGregory Neil Shapiro the parallelism inherent in multiple processes.</LI> 11340266059SGregory Neil Shapiro</OL> 11440266059SGregory Neil Shapiro 115d0cef73dSGregory Neil Shapiro<P> 11640266059SGregory Neil ShapiroEach filter may communicate with multiple MTAs at the same time over 117d0cef73dSGregory Neil Shapirolocal or remote connections, using multiple threads of execution. 118d0cef73dSGregory Neil Shapiro<A HREF="#figure-1">Figure 1</A> illustrates a possible network of 11940266059SGregory Neil Shapirocommunication channels between a site's filters, its MTAs, and other 12040266059SGregory Neil ShapiroMTAs on the network: 121d0cef73dSGregory Neil Shapiro</P> 122d0cef73dSGregory Neil Shapiro<DIV align="center"> 123d0cef73dSGregory Neil Shapiro<A name="figure-1"><IMG src="figure1.jpg" ALT=""></A><BR> 124d0cef73dSGregory Neil Shapiro<B>Figure 1: A set of MTA's interacting with a set of filters.</B> 125d0cef73dSGregory Neil Shapiro</DIV> 126d0cef73dSGregory Neil Shapiro<P> 12740266059SGregory Neil ShapiroThe Milter library (libmilter) implements the communication protocol. 12840266059SGregory Neil ShapiroIt accepts connections from various MTAs, passes the relevant data to 12940266059SGregory Neil Shapirothe filter through callbacks, then makes appropriate responses based 13040266059SGregory Neil Shapiroon return codes. A filter may also send data to the MTA as a result 131d0cef73dSGregory Neil Shapiroof library calls. <A href="#figure-2">Figure 2</A> shows a single 13240266059SGregory Neil Shapirofilter process processing messages from two MTAs: 133d0cef73dSGregory Neil Shapiro</P> 134d0cef73dSGregory Neil Shapiro<DIV align="center"> 135d0cef73dSGregory Neil Shapiro<IMG src="figure2.jpg" ALT=""><BR> 136d0cef73dSGregory Neil Shapiro<B>Figure 2: A filter handling simultaneous requests from two MTA's.</B> 137d0cef73dSGregory Neil Shapiro</DIV> 138d0cef73dSGregory Neil Shapiro<HR size="1"> 139d0cef73dSGregory Neil Shapiro<FONT size="-1"> 1405dd76dd0SGregory Neil ShapiroCopyright (c) 2000, 2003 Proofpoint, Inc. and its suppliers. 14140266059SGregory Neil ShapiroAll rights reserved. 142d0cef73dSGregory Neil Shapiro<BR> 14340266059SGregory Neil ShapiroBy using this file, you agree to the terms and conditions set 1445ef517c0SGregory Neil Shapiroforth in the LICENSE. 145d0cef73dSGregory Neil Shapiro</FONT> 146d0cef73dSGregory Neil Shapiro</BODY> 147d0cef73dSGregory Neil Shapiro</HTML> 148
