design.html revision 112810 
1<html>
2<head>
3<title>Architecture</title>
4</head>
5<body>
6
7<h1>Architecture</h1>
8
9<h2>Contents</h2>
10
11<ul>
12    <li>Design Goals
13    <li>Implementing Filtering Policies
14    <li>MTA - Filter Communication
15</ul>
16
17<h2>Goals</h2>
18
19The Sendmail Content Management API (Milter) provides an interface for
20third-party software to validate and modify messages as they pass
21through the mail transport system.  Filters can process messages'
22connection (IP) information, envelope protocol elements, message
23headers, and/or message body contents, and modify a message's
24recipients, headers, and body.  The MTA configuration file specifies
25which filters are to be applied, and in what order, allowing an
26administrator to combine multiple independently-developed filters.
27
28<p>
29We expect to see both vendor-supplied, configurable mail filtering
30applications and a multiplicity of script-like filters designed by and
31for MTA administrators.  A certain degree of coding sophistication and
32domain knowledge on the part of the filter provider is assumed.  This
33allows filters to exercise fine-grained control at the SMTP level.
34However, as will be seen in the example, many filtering applications
35can be written with relatively little protocol knowledge.
36
37<p>
38Given these expectations, the API is designed to achieve the following
39goals:
40
41<OL>
42  <LI>Safety/security.
43        Filter processes should not need to run as root
44        (of course, they can if required, but that is a local issue);
45        this will simplify coding
46        and limit the impact of security flaws in the filter program.
47<p>
48  <LI>Reliability.
49        Coding failures in a Milter process that cause that process
50        to hang or core-dump
51        should not stop mail delivery.
52        Faced with such a failure,
53        sendmail should use a default mechanism,
54        either behaving as if the filter were not present
55        or as if a required resource were unavailable.
56        The latter failure mode will generally have sendmail return
57        a 4xx SMTP code (although in later phases of the SMTP protocol
58        it may cause the mail to be queued for later processing).
59<p>
60  <LI>Simplicity.
61        The API should make implementation of a new filter
62        no more difficult than absolutely necessary.
63        Subgoals include:
64        <UL>
65          <LI>Encourage good thread practice
66              by defining thread-clean interfaces including local data hooks.
67          <LI>Provide all interfaces required
68              while avoiding unnecessary pedanticism.
69        </UL>
70<p>
71  <LI>Performance.
72        Simple filters should not seriously impact overall MTA performance.
73</OL>
74
75<h2>Implementing Filtering Policies</h2>
76
77Milter is designed to allow a server administrator to combine
78third-party filters to implement a desired mail filtering policy.  For
79example, if a site wished to scan incoming mail for viruses on several
80platforms, eliminate unsolicited commercial email, and append a mandated
81footer to selected incoming messages, the administrator could configure
82the MTA to filter messages first through a server based anti-virus
83engine, then via a large-scale spam-catching service, and finally
84append the desired footer if the message still met requisite criteria.
85Any of these filters could be added or changed independently.
86
87<p>
88Thus the site administrator, not the filter writer, controls the
89overall mail filtering environment.  In particular, he/she must decide
90which filters are run, in what order they are run, and how they
91communicate with the MTA.  These parameters, as well as the
92actions to be taken if a filter becomes unavailable, are selectable
93during MTA configuration.  <a href="installation.html">Further
94details</a> are available later in this document.
95
96<h2>MTA - Filter communication</h2>
97
98Filters run as separate processes, outside of the sendmail address
99space.  The benefits of this are threefold:
100
101<OL>
102  <LI>The filter need not run with "root" permissions, thereby
103        avoiding a large family of potential security problems.</LI>
104
105  <LI>Failures in a particular filter will not affect the MTA or
106        other filters.</LI>
107
108  <LI>The filter can potentially have higher performance because of
109        the parallelism inherent in multiple processes.</LI>
110</OL>
111
112<p>
113Each filter may communicate with multiple MTAs at the same time over
114local or remote connections, using multiple threads of execution.  <a
115href="#figure-1">Figure 1</a> illustrates a possible network of
116communication channels between a site's filters, its MTAs, and other
117MTAs on the network:
118</p>
119<div align="center">
120<a name="figure-1"><img src="figure1.jpg" ALT=""></A><br>
121<b>Figure 1: A set of MTA's interacting with a set of filters.</b>
122</div>
123<p>
124The Milter library (libmilter) implements the communication protocol.
125It accepts connections from various MTAs, passes the relevant data to
126the filter through callbacks, then makes appropriate responses based
127on return codes.  A filter may also send data to the MTA as a result
128of library calls.  <a href="#figure-2">Figure 2</a> shows a single
129filter process processing messages from two MTAs:
130</p>
131<div align="center">
132<img src="figure2.jpg" ALT=""><br>
133<b>Figure 2: A filter handling simultaneous requests from two MTA's.</b>
134</div>
135<hr size="1">
136<font size="-1">
137Copyright (c) 2000, 2003 Sendmail, Inc. and its suppliers.
138All rights reserved.
139<br>
140By using this file, you agree to the terms and conditions set
141forth in the LICENSE.
142</font>
143</body>
144</html>
145