xref: /freebsd/contrib/sendmail/libmilter/docs/overview.html (revision 39beb93c3f8bdbf72a61fda42300b5ebed7390c8)
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
24In addition to its own initialization,
25libmilter expects a filter to initialize several parameters
26before 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>
40If the filter fails to initialize libmilter,
41or if one or more of the parameters it has passed are invalid,
42a subsequent call to smfi_main will fail.
43
44<H2><A NAME="ControlFlow">Control Flow</A></H2>
45
46<P>
47The following pseudocode describes the filtering process from the
48perspective of a set of <CODE>N</CODE> MTA's,
49each corresponding to a connection.
50Callbacks are shown beside the processing stages in which they are invoked;
51if no callbacks are defined for a particular stage,
52that stage may be bypassed.
53Though it is not shown,
54processing may be aborted at any time during a message,
55in which case the
56<A HREF="xxfi_abort.html">xxfi_abort</A> callback is invoked and control
57returns to <CODE>MESSAGE</CODE>.
58<P>
59<PRE>
60For 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>)
64MESSAGE: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>
92To write a filter, a vendor supplies callbacks to process relevant
93parts of a message transaction.
94The library then controls all sequencing, threading,
95and protocol exchange with the MTA.
96<A HREF="#figure-3">Figure 3</A> outlines control flow for a filter
97process, 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>
122Note that although only a single message is shown above, multiple
123messages may be sent in a single connection.
124Note also that a message or connection may be aborted by
125either the remote host or the MTA
126at any point during the SMTP transaction.
127f this occurs during a message (between the MAIL command and the final "."),
128the 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
131connection closes.
132
133<H2><A NAME="Multithreading">Multithreading</A></H2>
134
135<P>
136A single filter process may handle any number of connections
137simultaneously.
138All filtering callbacks must therefore be reentrant,
139and use some appropriate external synchronization methods to access
140global data.
141Furthermore, since there is not a one-to-one correspondence
142between threads and connections
143(N connections mapped onto M threads, M &lt;= N),
144connection-specific data must be accessed
145through the handles provided by the Milter library.
146The programmer cannot rely on library-supplied thread-specific data blocks
147(e.g., <CODE>pthread_getspecific(3)</CODE>) to store connection-specific data.
148See 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
154Since filters are likely to be long-lived,
155and to handle many connections,
156proper deallocation of per-connection resources is important.
157The lifetime of a connection is bracketed by calls to the
158callbacks <A HREF="xxfi_connect.html">xxfi_connect</A> and
159<A HREF="xxfi_close.html">xxfi_close</A>.
160Therefore connection-specific
161resources (accessed via <A HREF="smfi_getpriv.html">smfi_getpriv</A>
162and <A HREF="smfi_setpriv.html">smfi_setpriv</A>) may be allocated in
163<A HREF="xxfi_connect.html">xxfi_connect</A>,
164and should be freed in
165<A HREF="xxfi_close.html">xxfi_close</A>.
166For further information see
167the <A HREF="api.html#conn-msg">discussion</A> of message- versus
168connection-oriented routines.
169In particular,
170note that there is only one connection-specific data pointer per connection.
171<P>
172
173Each 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>),
177implying that message-specific resources can be allocated
178and reclaimed in these routines.
179Since the messages in a connection are processed sequentially by each filter,
180there will be only one active message associated with a given
181connection and filter (and connection-private data block).
182These 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>,
185and must be reclaimed in
186<A HREF="xxfi_abort.html">xxfi_abort</A>.
187
188<H2><A NAME="SignalHandling">Signal Handling</A></H2>
189
190libmilter takes care of signal handling,
191the filters are not influenced directly by signals.
192There are basically two types of signal handlers:
193
194<OL>
195<LI><TT>Stop</TT>: no new connections from the MTA will be accepted,
196but existing connections are allowed to continue.
197<LI><TT>Abort</TT>: all filters will be stopped as soon as the next
198communication with the MTA happens.
199</OL>
200
201Filters are not terminated asynchronously
202(except by signals that can't be caught).
203In 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">
208Copyright (c) 2000, 2001, 2003, 2006 Sendmail, Inc. and its suppliers.
209All rights reserved.
210<BR>
211By using this file, you agree to the terms and conditions set
212forth in the LICENSE.
213</FONT>
214</BODY>
215</HTML>
216