140266059SGregory Neil Shapiro<html> 240266059SGregory Neil Shapiro<head> 340266059SGregory Neil Shapiro<title>Architecture</title> 440266059SGregory Neil Shapiro</head> 540266059SGregory Neil Shapiro<body> 6e92d3f3fSGregory Neil Shapiro<!-- 7e92d3f3fSGregory Neil Shapiro$Id: design.html,v 1.11 2003/03/05 19:57:54 ca Exp $ 8e92d3f3fSGregory Neil Shapiro--> 940266059SGregory Neil Shapiro 1040266059SGregory Neil Shapiro<h1>Architecture</h1> 1140266059SGregory Neil Shapiro 1240266059SGregory Neil Shapiro<h2>Contents</h2> 1340266059SGregory Neil Shapiro 1440266059SGregory Neil Shapiro<ul> 1540266059SGregory Neil Shapiro <li>Design Goals 1640266059SGregory Neil Shapiro <li>Implementing Filtering Policies 1740266059SGregory Neil Shapiro <li>MTA - Filter Communication 1840266059SGregory Neil Shapiro</ul> 1940266059SGregory Neil Shapiro 2040266059SGregory 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 3140266059SGregory 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 4040266059SGregory 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. 5040266059SGregory 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). 6240266059SGregory 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> 7340266059SGregory 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 7840266059SGregory 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 9040266059SGregory 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 9640266059SGregory Neil Shapiroduring MTA configuration. <a href="installation.html">Further 9740266059SGregory Neil Shapirodetails</a> are available later in this document. 9840266059SGregory Neil Shapiro 9940266059SGregory 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 11540266059SGregory Neil Shapiro<p> 11640266059SGregory Neil ShapiroEach filter may communicate with multiple MTAs at the same time over 11740266059SGregory Neil Shapirolocal or remote connections, using multiple threads of execution. <a 11840266059SGregory Neil Shapirohref="#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: 12140266059SGregory Neil Shapiro</p> 12240266059SGregory Neil Shapiro<div align="center"> 12340266059SGregory Neil Shapiro<a name="figure-1"><img src="figure1.jpg" ALT=""></A><br> 12440266059SGregory Neil Shapiro<b>Figure 1: A set of MTA's interacting with a set of filters.</b> 12540266059SGregory Neil Shapiro</div> 12640266059SGregory 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 13140266059SGregory Neil Shapiroof library calls. <a href="#figure-2">Figure 2</a> shows a single 13240266059SGregory Neil Shapirofilter process processing messages from two MTAs: 13340266059SGregory Neil Shapiro</p> 13440266059SGregory Neil Shapiro<div align="center"> 13540266059SGregory Neil Shapiro<img src="figure2.jpg" ALT=""><br> 13640266059SGregory Neil Shapiro<b>Figure 2: A filter handling simultaneous requests from two MTA's.</b> 13740266059SGregory Neil Shapiro</div> 13840266059SGregory Neil Shapiro<hr size="1"> 13940266059SGregory Neil Shapiro<font size="-1"> 1405ef517c0SGregory Neil ShapiroCopyright (c) 2000, 2003 Sendmail, Inc. and its suppliers. 14140266059SGregory Neil ShapiroAll rights reserved. 14240266059SGregory Neil Shapiro<br> 14340266059SGregory Neil ShapiroBy using this file, you agree to the terms and conditions set 1445ef517c0SGregory Neil Shapiroforth in the LICENSE. 14540266059SGregory Neil Shapiro</font> 14640266059SGregory Neil Shapiro</body> 14740266059SGregory Neil Shapiro</html> 148
