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.21 2010/12/14 20:59:52 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 (<A HREF="xxfi_connect.html">xxfi_connect</A>)
  64         For each filter
  65                 process helo/ehlo (<A HREF="xxfi_helo.html">xxfi_helo</A>)
  66 MESSAGE:For each message in this connection (sequentially)
  67         {
  68                 For each filter
  69                         process sender (<A HREF="xxfi_envfrom.html">xxfi_envfrom</A>)
  70                 For each recipient
  71                 {
  72                         For each filter
  73                                 process recipient (<A HREF="xxfi_envrcpt.html">xxfi_envrcpt</A>)
  74                 }
  75                 For each filter
  76                 {
  77                         process DATA (<A HREF="xxfi_data.html">xxfi_data</A>)
  78                         For each header
  79                                 process header (<A HREF="xxfi_header.html">xxfi_header</A>)
  80                         process end of headers (<A HREF="xxfi_eoh.html">xxfi_eoh</A>)
  81                         For each body block
  82                                 process this body block (<A HREF="xxfi_body.html">xxfi_body</A>)
  83                         process end of message (<A HREF="xxfi_eom.html">xxfi_eom</A>)
  84                 }
  85         }
  86         For each filter
  87                 process end of connection (<A HREF="xxfi_close.html">xxfi_close</A>)
  88 }
  89 </PRE>
  90
  91 <P>Note: Filters are contacted in order defined in config file.</P>
  92
  93 <P>
  94 To write a filter, a vendor supplies callbacks to process relevant
  95 parts of a message transaction.
  96 The library then controls all sequencing, threading,
  97 and protocol exchange with the MTA.
  98 <A HREF="#figure-3">Figure 3</A> outlines control flow for a filter
  99 process, showing where different callbacks are invoked.
 100 </P>
 101
 102 <DIV ALIGN="center"><A NAME="figure-3"></A>
 103 <TABLE border=1 cellspacing=0 cellpadding=2 width="70%">
 104 <TR bgcolor="#dddddd"><TH>SMTP Commands</TH><TH>Milter Callbacks</TH></TR>
 105 <TR><TD>(open SMTP connection)</TD><TD>xxfi_connect</TD></TR>
 106 <TR><TD>HELO ...</TD><TD>xxfi_helo</TD></TR>
 107 <TR><TD>MAIL From: ...</TD><TD>xxfi_envfrom</TD></TR>
 108 <TR><TD>RCPT To: ...</TD><TD>xxfi_envrcpt</TD></TR>
 109 <TR><TD>[more RCPTs]</TD><TD>[xxfi_envrcpt]</TD></TR>
 110 <TR><TD>DATA</TD><TD>xxfi_data</TD></TR>
 111 <TR><TD>Header: ...</TD><TD>xxfi_header</TD></TR>
 112 <TR><TD>[more headers]</TD><TD>[xxfi_header]</TD></TR>
 113 <TR><TD>&nbsp;</TD><TD>xxfi_eoh</TD></TR>
 114 <TR><TD>body... </TD><TD>xxfi_body</TD></TR>
 115 <TR><TD>[more body...]</TD><TD>[xxfi_body]</TD></TR>
 116 <TR><TD>.</TD><TD>xxfi_eom</TD></TR>
 117 <TR><TD>QUIT</TD><TD>xxfi_close</TD></TR>
 118 <TR><TD>(close SMTP connection)</TD><TD>&nbsp;</TD></TR>
 119 </TABLE>
 120 <B>Figure 3: Milter callbacks related to an SMTP transaction.</B>
 121 </DIV>
 122
 123 <P>
 124 Note that although only a single message is shown above, multiple
 125 messages may be sent in a single connection.
 126 Note also that a message or connection may be aborted by
 127 either the remote host or the MTA
 128 at any point during the SMTP transaction.
 129 If this occurs during a message (between the MAIL command and the final "."),
 130 the filter's
 131 <A HREF="xxfi_abort.html">xxfi_abort</A> routine will be called.
 132 <A HREF="xxfi_close.html">xxfi_close</A> is called any time the
 133 connection closes.
 134
 135 <H2><A NAME="Multithreading">Multithreading</A></H2>
 136
 137 <P>
 138 A single filter process may handle any number of connections
 139 simultaneously.
 140 All filtering callbacks must therefore be reentrant,
 141 and use some appropriate external synchronization methods to access
 142 global data.
 143 Furthermore, since there is not a one-to-one correspondence
 144 between threads and connections
 145 (N connections mapped onto M threads, M &lt;= N),
 146 connection-specific data must be accessed
 147 through the handles provided by the Milter library.
 148 The programmer cannot rely on library-supplied thread-specific data blocks
 149 (e.g., <CODE>pthread_getspecific(3)</CODE>) to store connection-specific data.
 150 See the API documentation for
 151 <A HREF="smfi_setpriv.html">smfi_setpriv</A> and
 152 <A HREF="smfi_getpriv.html">smfi_getpriv</A> for details.
 153
 154 <H2><A NAME="ResourceManagement">Resource Management</A></H2>
 155
 156 Since filters are likely to be long-lived,
 157 and to handle many connections,
 158 proper deallocation of per-connection resources is important.
 159 The lifetime of a connection is bracketed by calls to the
 160 callbacks <A HREF="xxfi_connect.html">xxfi_connect</A> and
 161 <A HREF="xxfi_close.html">xxfi_close</A>.
 162 Therefore connection-specific
 163 resources (accessed via <A HREF="smfi_getpriv.html">smfi_getpriv</A>
 164 and <A HREF="smfi_setpriv.html">smfi_setpriv</A>) may be allocated in
 165 <A HREF="xxfi_connect.html">xxfi_connect</A>,
 166 and should be freed in
 167 <A HREF="xxfi_close.html">xxfi_close</A>.
 168 For further information see
 169 the <A HREF="api.html#conn-msg">discussion</A> of message- versus
 170 connection-oriented routines.
 171 In particular,
 172 note that there is only one connection-specific data pointer per connection.
 173 <P>
 174
 175 Each message is bracketed by calls to
 176 <A HREF="xxfi_envfrom.html">xxfi_envfrom</A> and
 177 <A HREF="xxfi_eom.html">xxfi_eom</A> (or
 178 <A HREF="xxfi_abort.html">xxfi_abort</A>),
 179 implying that message-specific resources can be allocated
 180 and reclaimed in these routines.
 181 Since the messages in a connection are processed sequentially by each filter,
 182 there will be only one active message associated with a given
 183 connection and filter (and connection-private data block).
 184 These resources must still be accessed through
 185 <A HREF="smfi_getpriv.html">smfi_getpriv</A> and
 186 <A HREF="smfi_setpriv.html">smfi_setpriv</A>,
 187 and must be reclaimed in
 188 <A HREF="xxfi_abort.html">xxfi_abort</A>.
 189
 190 <H2><A NAME="SignalHandling">Signal Handling</A></H2>
 191
 192 libmilter takes care of signal handling,
 193 the filters are not influenced directly by signals.
 194 There are basically two types of signal handlers:
 195
 196 <OL>
 197 <LI><TT>Stop</TT>: no new connections from the MTA will be accepted,
 198 but existing connections are allowed to continue.
 199 <LI><TT>Abort</TT>: all filters will be stopped as soon as the next
 200 communication with the MTA happens.
 201 </OL>
 202
 203 Filters are not terminated asynchronously
 204 (except by signals that can't be caught).
 205 In the case of <TT>Abort</TT> the
 206 <A HREF="xxfi_abort.html">xxfi_abort</A> callback is invoked.
 207
 208 <HR size="1">
 209 <FONT size="-1">
 210 Copyright (c) 2000, 2001, 2003, 2006 Sendmail, Inc. and its suppliers.
 211 All rights reserved.
 212 <BR>
 213 By using this file, you agree to the terms and conditions set
 214 forth in the LICENSE.
 215 </FONT>
 216 </BODY>
 217 </HTML>