3 <TITLE>Technical Overview</TITLE>
7 $Id: overview.html,v 1.19 2006/12/21 18:23:47 ca Exp $
10 <H1>Technical Overview</H1>
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>
22 <H2><A NAME="Initialization">Initialization</A></H2>
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>:
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>).
32 <LI>The socket address to be used when communicating with the MTA
33 (required, see <A HREF="smfi_setconn.html">smfi_setconn</A>).
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>).
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.
44 <H2><A NAME="ControlFlow">Control Flow</A></H2>
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,
56 <A HREF="xxfi_abort.html">xxfi_abort</A> callback is invoked and control
57 returns to <CODE>MESSAGE</CODE>.
60 For each of N connections
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)
67 process sender (<A HREF="xxfi_envfrom.html">xxfi_envfrom</A>)
71 process recipient (<A HREF="xxfi_envrcpt.html">xxfi_envrcpt</A>)
75 process DATA (<A HREF="xxfi_data.html">xxfi_data</A>)
77 process header (<A HREF="xxfi_header.html">xxfi_header</A>)
78 process end of headers (<A HREF="xxfi_eoh.html">xxfi_eoh</A>)
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>)
85 process end of connection (<A HREF="xxfi_close.html">xxfi_close</A>)
89 <P>Note: Filters are contacted in order defined in config file.</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.
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> </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> </TD></TR>
118 <B>Figure 3: Milter callbacks related to an SMTP transaction.</B>
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 "."),
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
133 <H2><A NAME="Multithreading">Multithreading</A></H2>
136 A single filter process may handle any number of connections
138 All filtering callbacks must therefore be reentrant,
139 and use some appropriate external synchronization methods to access
141 Furthermore, since there is not a one-to-one correspondence
142 between threads and connections
143 (N connections mapped onto M threads, M <= 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.
152 <H2><A NAME="ResourceManagement">Resource Management</A></H2>
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.
170 note that there is only one connection-specific data pointer per connection.
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>.
188 <H2><A NAME="SignalHandling">Signal Handling</A></H2>
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:
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.
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.
208 Copyright (c) 2000, 2001, 2003, 2006 Sendmail, Inc. and its suppliers.
211 By using this file, you agree to the terms and conditions set
212 forth in the LICENSE.