contrib/sendmail/libmilter/docs/overview.html

   1 <HTML>
   2 <HEAD>
   3 <TITLE>Technical Overview</TITLE>
   4 </HEAD>
   5 <BODY>
   6 <!--
   7 $Id: overview.html,v 1.19 2006/12/21 18:23:47 ca Exp $
   8 -->
   9
  10 <H1>Technical Overview</H1>
  11
  12 <H2>Contents</H2>
  13
  14 <UL>
  15     <LI><A HREF="#Initialization">Initialization</A>
  16     <LI><A HREF="#ControlFlow">Control Flow</A>
  17     <LI><A HREF="#Multithreading">Multithreading</A>
  18     <LI><A HREF="#ResourceManagement">Resource Management</A>
  19     <LI><A HREF="#SignalHandling">Signal Handling</A>
  20 </UL>
  21
  22 <H2><A NAME="Initialization">Initialization</A></H2>
  23
  24 In addition to its own initialization,
  25 libmilter expects a filter to initialize several parameters
  26 before calling <A HREF="smfi_main.html">smfi_main</A>:
  27 <UL>
  28     <LI>The callbacks the filter wishes to be called, and the types of
  29     message modification it intends to perform (required, see
  30     <A HREF="smfi_register.html">smfi_register</A>).
  31
  32     <LI>The socket address to be used when communicating with the MTA
  33     (required, see <A HREF="smfi_setconn.html">smfi_setconn</A>).
  34
  35     <LI>The number of seconds to wait for MTA connections before
  36     timing out (optional, see
  37     <A HREF="smfi_settimeout.html">smfi_settimeout</A>).
  38 </UL>
  39 <P>
  40 If the filter fails to initialize libmilter,
  41 or if one or more of the parameters it has passed are invalid,
  42 a subsequent call to smfi_main will fail.
  43
  44 <H2><A NAME="ControlFlow">Control Flow</A></H2>
  45
  46 <P>
  47 The following pseudocode describes the filtering process from the
  48 perspective of a set of <CODE>N</CODE> MTA's,
  49 each corresponding to a connection.
  50 Callbacks are shown beside the processing stages in which they are invoked;
  51 if no callbacks are defined for a particular stage,
  52 that stage may be bypassed.
  53 Though it is not shown,
  54 processing may be aborted at any time during a message,
  55 in which case the
  56 <A HREF="xxfi_abort.html">xxfi_abort</A> callback is invoked and control
  57 returns to <CODE>MESSAGE</CODE>.
  58 <P>
  59 <PRE>
  60 For each of N connections
  61 {
  62         For each filter
  63                 process connection/helo (<A HREF="xxfi_connect.html">xxfi_connect</A>, <A HREF="xxfi_helo.html">xxfi_helo</A>)
  64 MESSAGE:For each message in this connection (sequentially)
  65         {
  66                 For each filter
  67                         process sender (<A HREF="xxfi_envfrom.html">xxfi_envfrom</A>)
  68                 For each recipient
  69                 {
  70                         For each filter
  71                                 process recipient (<A HREF="xxfi_envrcpt.html">xxfi_envrcpt</A>)
  72                 }
  73                 For each filter
  74                 {
  75                         process DATA (<A HREF="xxfi_data.html">xxfi_data</A>)
  76                         For each header
  77                                 process header (<A HREF="xxfi_header.html">xxfi_header</A>)
  78                         process end of headers (<A HREF="xxfi_eoh.html">xxfi_eoh</A>)
  79                         For each body block
  80                                 process this body block (<A HREF="xxfi_body.html">xxfi_body</A>)
  81                         process end of message (<A HREF="xxfi_eom.html">xxfi_eom</A>)
  82                 }
  83         }
  84         For each filter
  85                 process end of connection (<A HREF="xxfi_close.html">xxfi_close</A>)
  86 }
  87 </PRE>
  88
  89 <P>Note: Filters are contacted in order defined in config file.</P>
  90
  91 <P>
  92 To write a filter, a vendor supplies callbacks to process relevant
  93 parts of a message transaction.
  94 The library then controls all sequencing, threading,
  95 and protocol exchange with the MTA.
  96 <A HREF="#figure-3">Figure 3</A> outlines control flow for a filter
  97 process, showing where different callbacks are invoked.
  98 </P>
  99
 100 <DIV ALIGN="center"><A NAME="figure-3"></A>
 101 <TABLE border=1 cellspacing=0 cellpadding=2 width="70%">
 102 <TR bgcolor="#dddddd"><TH>SMTP Commands</TH><TH>Milter Callbacks</TH></TR>
 103 <TR><TD>(open SMTP connection)</TD><TD>xxfi_connect</TD></TR>
 104 <TR><TD>HELO ...</TD><TD>xxfi_helo</TD></TR>
 105 <TR><TD>MAIL From: ...</TD><TD>xxfi_envfrom</TD></TR>
 106 <TR><TD>RCPT To: ...</TD><TD>xxfi_envrcpt</TD></TR>
 107 <TR><TD>[more RCPTs]</TD><TD>[xxfi_envrcpt]</TD></TR>
 108 <TR><TD>DATA</TD><TD>xxfi_data</TD></TR>
 109 <TR><TD>Header: ...</TD><TD>xxfi_header</TD></TR>
 110 <TR><TD>[more headers]</TD><TD>[xxfi_header]</TD></TR>
 111 <TR><TD>&nbsp;</TD><TD>xxfi_eoh</TD></TR>
 112 <TR><TD>body... </TD><TD>xxfi_body</TD></TR>
 113 <TR><TD>[more body...]</TD><TD>[xxfi_body]</TD></TR>
 114 <TR><TD>.</TD><TD>xxfi_eom</TD></TR>
 115 <TR><TD>QUIT</TD><TD>xxfi_close</TD></TR>
 116 <TR><TD>(close SMTP connection)</TD><TD>&nbsp;</TD></TR>
 117 </TABLE>
 118 <B>Figure 3: Milter callbacks related to an SMTP transaction.</B>
 119 </DIV>
 120
 121 <P>
 122 Note that although only a single message is shown above, multiple
 123 messages may be sent in a single connection.
 124 Note also that a message or connection may be aborted by
 125 either the remote host or the MTA
 126 at any point during the SMTP transaction.
 127 f this occurs during a message (between the MAIL command and the final "."),
 128 the filter's
 129 <A HREF="xxfi_abort.html">xxfi_abort</A> routine will be called.
 130 <A HREF="xxfi_close.html">xxfi_close</A> is called any time the
 131 connection closes.
 132
 133 <H2><A NAME="Multithreading">Multithreading</A></H2>
 134
 135 <P>
 136 A single filter process may handle any number of connections
 137 simultaneously.
 138 All filtering callbacks must therefore be reentrant,
 139 and use some appropriate external synchronization methods to access
 140 global data.
 141 Furthermore, since there is not a one-to-one correspondence
 142 between threads and connections
 143 (N connections mapped onto M threads, M &lt;= N),
 144 connection-specific data must be accessed
 145 through the handles provided by the Milter library.
 146 The programmer cannot rely on library-supplied thread-specific data blocks
 147 (e.g., <CODE>pthread_getspecific(3)</CODE>) to store connection-specific data.
 148 See the API documentation for
 149 <A HREF="smfi_setpriv.html">smfi_setpriv</A> and
 150 <A HREF="smfi_getpriv.html">smfi_getpriv</A> for details.
 151
 152 <H2><A NAME="ResourceManagement">Resource Management</A></H2>
 153
 154 Since filters are likely to be long-lived,
 155 and to handle many connections,
 156 proper deallocation of per-connection resources is important.
 157 The lifetime of a connection is bracketed by calls to the
 158 callbacks <A HREF="xxfi_connect.html">xxfi_connect</A> and
 159 <A HREF="xxfi_close.html">xxfi_close</A>.
 160 Therefore connection-specific
 161 resources (accessed via <A HREF="smfi_getpriv.html">smfi_getpriv</A>
 162 and <A HREF="smfi_setpriv.html">smfi_setpriv</A>) may be allocated in
 163 <A HREF="xxfi_connect.html">xxfi_connect</A>,
 164 and should be freed in
 165 <A HREF="xxfi_close.html">xxfi_close</A>.
 166 For further information see
 167 the <A HREF="api.html#conn-msg">discussion</A> of message- versus
 168 connection-oriented routines.
 169 In particular,
 170 note that there is only one connection-specific data pointer per connection.
 171 <P>
 172
 173 Each message is bracketed by calls to
 174 <A HREF="xxfi_envfrom.html">xxfi_envfrom</A> and
 175 <A HREF="xxfi_eom.html">xxfi_eom</A> (or
 176 <A HREF="xxfi_abort.html">xxfi_abort</A>),
 177 implying that message-specific resources can be allocated
 178 and reclaimed in these routines.
 179 Since the messages in a connection are processed sequentially by each filter,
 180 there will be only one active message associated with a given
 181 connection and filter (and connection-private data block).
 182 These resources must still be accessed through
 183 <A HREF="smfi_getpriv.html">smfi_getpriv</A> and
 184 <A HREF="smfi_setpriv.html">smfi_setpriv</A>,
 185 and must be reclaimed in
 186 <A HREF="xxfi_abort.html">xxfi_abort</A>.
 187
 188 <H2><A NAME="SignalHandling">Signal Handling</A></H2>
 189
 190 libmilter takes care of signal handling,
 191 the filters are not influenced directly by signals.
 192 There are basically two types of signal handlers:
 193
 194 <OL>
 195 <LI><TT>Stop</TT>: no new connections from the MTA will be accepted,
 196 but existing connections are allowed to continue.
 197 <LI><TT>Abort</TT>: all filters will be stopped as soon as the next
 198 communication with the MTA happens.
 199 </OL>
 200
 201 Filters are not terminated asynchronously
 202 (except by signals that can't be caught).
 203 In the case of <TT>Abort</TT> the
 204 <A HREF="xxfi_abort.html">xxfi_abort</A> callback is invoked.
 205
 206 <HR size="1">
 207 <FONT size="-1">
 208 Copyright (c) 2000, 2001, 2003, 2006 Sendmail, Inc. and its suppliers.
 209 All rights reserved.
 210 <BR>
 211 By using this file, you agree to the terms and conditions set
 212 forth in the LICENSE.
 213 </FONT>
 214 </BODY>
 215 </HTML>