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<!-- 74313cc83SGregory 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 34*5b0945b5SGregory Neil Shapirofor MTA administrators. 35*5b0945b5SGregory Neil ShapiroA certain degree of coding sophistication and 36*5b0945b5SGregory Neil Shapirodomain knowledge on the part of the filter provider is assumed. 37*5b0945b5SGregory Neil ShapiroThis allows filters to exercise fine-grained control at the SMTP level. 3840266059SGregory Neil ShapiroHowever, as will be seen in the example, many filtering applications 39*5b0945b5SGregory Neil Shapirocan be written with relatively little protocol knowledge, 40*5b0945b5SGregory Neil Shapirobut a basic understanding (e.g., as documented in RFC 5321: 41*5b0945b5SGregory Neil Shapiro<EM>The dialog is purposely lock-step, one-at-a-time</EM>) 42*5b0945b5SGregory Neil Shapirois necessary. 4340266059SGregory Neil Shapiro 44d0cef73dSGregory Neil Shapiro<P> 4540266059SGregory Neil ShapiroGiven these expectations, the API is designed to achieve the following 4640266059SGregory Neil Shapirogoals: 4740266059SGregory Neil Shapiro 4840266059SGregory Neil Shapiro<OL> 4940266059SGregory Neil Shapiro <LI>Safety/security. 5040266059SGregory Neil Shapiro Filter processes should not need to run as root 5140266059SGregory Neil Shapiro (of course, they can if required, but that is a local issue); 5240266059SGregory Neil Shapiro this will simplify coding 5340266059SGregory Neil Shapiro and limit the impact of security flaws in the filter program. 54d0cef73dSGregory Neil Shapiro<P> 5540266059SGregory Neil Shapiro <LI>Reliability. 5640266059SGregory Neil Shapiro Coding failures in a Milter process that cause that process 5740266059SGregory Neil Shapiro to hang or core-dump 5840266059SGregory Neil Shapiro should not stop mail delivery. 5940266059SGregory Neil Shapiro Faced with such a failure, 6040266059SGregory Neil Shapiro sendmail should use a default mechanism, 6140266059SGregory Neil Shapiro either behaving as if the filter were not present 6240266059SGregory Neil Shapiro or as if a required resource were unavailable. 6340266059SGregory Neil Shapiro The latter failure mode will generally have sendmail return 6440266059SGregory Neil Shapiro a 4xx SMTP code (although in later phases of the SMTP protocol 6540266059SGregory Neil Shapiro it may cause the mail to be queued for later processing). 66d0cef73dSGregory Neil Shapiro<P> 6740266059SGregory Neil Shapiro <LI>Simplicity. 6840266059SGregory Neil Shapiro The API should make implementation of a new filter 6940266059SGregory Neil Shapiro no more difficult than absolutely necessary. 7040266059SGregory Neil Shapiro Subgoals include: 7140266059SGregory Neil Shapiro <UL> 7240266059SGregory Neil Shapiro <LI>Encourage good thread practice 7340266059SGregory Neil Shapiro by defining thread-clean interfaces including local data hooks. 7440266059SGregory Neil Shapiro <LI>Provide all interfaces required 7540266059SGregory Neil Shapiro while avoiding unnecessary pedanticism. 7640266059SGregory Neil Shapiro </UL> 77d0cef73dSGregory Neil Shapiro<P> 7840266059SGregory Neil Shapiro <LI>Performance. 7940266059SGregory Neil Shapiro Simple filters should not seriously impact overall MTA performance. 8040266059SGregory Neil Shapiro</OL> 8140266059SGregory Neil Shapiro 82d0cef73dSGregory Neil Shapiro<H2>Implementing Filtering Policies</H2> 8340266059SGregory Neil Shapiro 8440266059SGregory Neil ShapiroMilter is designed to allow a server administrator to combine 8540266059SGregory Neil Shapirothird-party filters to implement a desired mail filtering policy. For 8640266059SGregory Neil Shapiroexample, if a site wished to scan incoming mail for viruses on several 8740266059SGregory Neil Shapiroplatforms, eliminate unsolicited commercial email, and append a mandated 8840266059SGregory Neil Shapirofooter to selected incoming messages, the administrator could configure 8940266059SGregory Neil Shapirothe MTA to filter messages first through a server based anti-virus 9040266059SGregory Neil Shapiroengine, then via a large-scale spam-catching service, and finally 9140266059SGregory Neil Shapiroappend the desired footer if the message still met requisite criteria. 9240266059SGregory Neil ShapiroAny of these filters could be added or changed independently. 9340266059SGregory Neil Shapiro 94d0cef73dSGregory Neil Shapiro<P> 9540266059SGregory Neil ShapiroThus the site administrator, not the filter writer, controls the 9640266059SGregory Neil Shapirooverall mail filtering environment. In particular, he/she must decide 9740266059SGregory Neil Shapirowhich filters are run, in what order they are run, and how they 9840266059SGregory Neil Shapirocommunicate with the MTA. These parameters, as well as the 9940266059SGregory Neil Shapiroactions to be taken if a filter becomes unavailable, are selectable 100d0cef73dSGregory Neil Shapiroduring MTA configuration. <A href="installation.html">Further 101d0cef73dSGregory Neil Shapirodetails</A> are available later in this document. 10240266059SGregory Neil Shapiro 103d0cef73dSGregory Neil Shapiro<H2>MTA - Filter communication</H2> 10440266059SGregory Neil Shapiro 10540266059SGregory Neil ShapiroFilters run as separate processes, outside of the sendmail address 10640266059SGregory Neil Shapirospace. The benefits of this are threefold: 10740266059SGregory Neil Shapiro 10840266059SGregory Neil Shapiro<OL> 10940266059SGregory Neil Shapiro <LI>The filter need not run with "root" permissions, thereby 11040266059SGregory Neil Shapiro avoiding a large family of potential security problems.</LI> 11140266059SGregory Neil Shapiro 11240266059SGregory Neil Shapiro <LI>Failures in a particular filter will not affect the MTA or 11340266059SGregory Neil Shapiro other filters.</LI> 11440266059SGregory Neil Shapiro 11540266059SGregory Neil Shapiro <LI>The filter can potentially have higher performance because of 11640266059SGregory Neil Shapiro the parallelism inherent in multiple processes.</LI> 11740266059SGregory Neil Shapiro</OL> 11840266059SGregory Neil Shapiro 119d0cef73dSGregory Neil Shapiro<P> 12040266059SGregory Neil ShapiroEach filter may communicate with multiple MTAs at the same time over 121d0cef73dSGregory Neil Shapirolocal or remote connections, using multiple threads of execution. 122d0cef73dSGregory Neil Shapiro<A HREF="#figure-1">Figure 1</A> illustrates a possible network of 12340266059SGregory Neil Shapirocommunication channels between a site's filters, its MTAs, and other 12440266059SGregory Neil ShapiroMTAs on the network: 125d0cef73dSGregory Neil Shapiro</P> 126d0cef73dSGregory Neil Shapiro<DIV align="center"> 127d0cef73dSGregory Neil Shapiro<A name="figure-1"><IMG src="figure1.jpg" ALT=""></A><BR> 128d0cef73dSGregory Neil Shapiro<B>Figure 1: A set of MTA's interacting with a set of filters.</B> 129d0cef73dSGregory Neil Shapiro</DIV> 130d0cef73dSGregory Neil Shapiro<P> 13140266059SGregory Neil ShapiroThe Milter library (libmilter) implements the communication protocol. 13240266059SGregory Neil ShapiroIt accepts connections from various MTAs, passes the relevant data to 13340266059SGregory Neil Shapirothe filter through callbacks, then makes appropriate responses based 13440266059SGregory Neil Shapiroon return codes. A filter may also send data to the MTA as a result 135d0cef73dSGregory Neil Shapiroof library calls. <A href="#figure-2">Figure 2</A> shows a single 13640266059SGregory Neil Shapirofilter process processing messages from two MTAs: 137d0cef73dSGregory Neil Shapiro</P> 138d0cef73dSGregory Neil Shapiro<DIV align="center"> 139d0cef73dSGregory Neil Shapiro<IMG src="figure2.jpg" ALT=""><BR> 140d0cef73dSGregory Neil Shapiro<B>Figure 2: A filter handling simultaneous requests from two MTA's.</B> 141d0cef73dSGregory Neil Shapiro</DIV> 142d0cef73dSGregory Neil Shapiro<HR size="1"> 143d0cef73dSGregory Neil Shapiro<FONT size="-1"> 1445dd76dd0SGregory Neil ShapiroCopyright (c) 2000, 2003 Proofpoint, Inc. and its suppliers. 14540266059SGregory Neil ShapiroAll rights reserved. 146d0cef73dSGregory Neil Shapiro<BR> 14740266059SGregory Neil ShapiroBy using this file, you agree to the terms and conditions set 1485ef517c0SGregory Neil Shapiroforth in the LICENSE. 149d0cef73dSGregory Neil Shapiro</FONT> 150d0cef73dSGregory Neil Shapiro</BODY> 151d0cef73dSGregory Neil Shapiro</HTML> 152
