contrib/sendmail/libmilter/docs/design.html

   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
  22 The Sendmail Content Management API (Milter) provides an interface for
  23 third-party software to validate and modify messages as they pass
  24 through the mail transport system.  Filters can process messages'
  25 connection (IP) information, envelope protocol elements, message
  26 headers, and/or message body contents, and modify a message's
  27 recipients, headers, and body.  The MTA configuration file specifies
  28 which filters are to be applied, and in what order, allowing an
  29 administrator to combine multiple independently-developed filters.
  30
  31 <P>
  32 We expect to see both vendor-supplied, configurable mail filtering
  33 applications and a multiplicity of script-like filters designed by and
  34 for MTA administrators.
  35 A certain degree of coding sophistication and
  36 domain knowledge on the part of the filter provider is assumed.
  37 This allows filters to exercise fine-grained control at the SMTP level.
  38 However, as will be seen in the example, many filtering applications
  39 can be written with relatively little protocol knowledge,
  40 but a basic understanding (e.g., as documented in RFC 5321:
  41 <EM>The dialog is purposely lock-step, one-at-a-time</EM>)
  42 is necessary.
  43
  44 <P>
  45 Given these expectations, the API is designed to achieve the following
  46 goals:
  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
  84 Milter is designed to allow a server administrator to combine
  85 third-party filters to implement a desired mail filtering policy.  For
  86 example, if a site wished to scan incoming mail for viruses on several
  87 platforms, eliminate unsolicited commercial email, and append a mandated
  88 footer to selected incoming messages, the administrator could configure
  89 the MTA to filter messages first through a server based anti-virus
  90 engine, then via a large-scale spam-catching service, and finally
  91 append the desired footer if the message still met requisite criteria.
  92 Any of these filters could be added or changed independently.
  93
  94 <P>
  95 Thus the site administrator, not the filter writer, controls the
  96 overall mail filtering environment.  In particular, he/she must decide
  97 which filters are run, in what order they are run, and how they
  98 communicate with the MTA.  These parameters, as well as the
  99 actions to be taken if a filter becomes unavailable, are selectable
 100 during MTA configuration.  <A href="installation.html">Further
 101 details</A> are available later in this document.
 102
 103 <H2>MTA - Filter communication</H2>
 104
 105 Filters run as separate processes, outside of the sendmail address
 106 space.  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>
 120 Each filter may communicate with multiple MTAs at the same time over
 121 local or remote connections, using multiple threads of execution.
 122 <A HREF="#figure-1">Figure 1</A> illustrates a possible network of
 123 communication channels between a site's filters, its MTAs, and other
 124 MTAs 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>
 131 The Milter library (libmilter) implements the communication protocol.
 132 It accepts connections from various MTAs, passes the relevant data to
 133 the filter through callbacks, then makes appropriate responses based
 134 on return codes.  A filter may also send data to the MTA as a result
 135 of library calls.  <A href="#figure-2">Figure 2</A> shows a single
 136 filter 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">
 144 Copyright (c) 2000, 2003 Proofpoint, Inc. and its suppliers.
 145 All rights reserved.
 146 <BR>
 147 By using this file, you agree to the terms and conditions set
 148 forth in the LICENSE.
 149 </FONT>
 150 </BODY>
 151 </HTML>