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