140266059SGregory Neil Shapiro<html> 240266059SGregory Neil Shapiro<head> 340266059SGregory Neil Shapiro<title>Technical Overview</title> 440266059SGregory Neil Shapiro</head> 540266059SGregory Neil Shapiro<body> 640266059SGregory Neil Shapiro<!-- 740266059SGregory Neil Shapiro$Id: overview.html,v 1.12 2001/06/01 00:05:03 ca Exp $ 840266059SGregory Neil Shapiro--> 940266059SGregory Neil Shapiro 1040266059SGregory Neil Shapiro<h1>Technical Overview</h1> 1140266059SGregory Neil Shapiro 1240266059SGregory Neil Shapiro<h2>Contents</h2> 1340266059SGregory Neil Shapiro 1440266059SGregory Neil Shapiro<ul> 1540266059SGregory Neil Shapiro <li>Initialization 1640266059SGregory Neil Shapiro <li>Control flow 1740266059SGregory Neil Shapiro <li>Multithreading 1840266059SGregory Neil Shapiro <li>Resource Management 1940266059SGregory Neil Shapiro <li>Signal Handling 2040266059SGregory Neil Shapiro</ul> 2140266059SGregory Neil Shapiro 2240266059SGregory Neil Shapiro<h2>Initialization</h2> 2340266059SGregory Neil Shapiro 2440266059SGregory Neil ShapiroIn addition to its own initialization, libmilter expects a filter to initialize several parameters before calling <a href="smfi_main.html">smfi_main</a>: 2540266059SGregory Neil Shapiro<ul> 2640266059SGregory Neil Shapiro <li>The callbacks the filter wishes to be called, and the types of 2740266059SGregory Neil Shapiro message modification it intends to perform (required, see <a 2840266059SGregory Neil Shapiro href="smfi_register.html">smfi_register</a>). 2940266059SGregory Neil Shapiro 3040266059SGregory Neil Shapiro <li>The socket address to be used when communicating with the MTA 3140266059SGregory Neil Shapiro (required, see <a href="smfi_setconn.html">smfi_setconn</a>). 3240266059SGregory Neil Shapiro 3340266059SGregory Neil Shapiro <li>The number of seconds to wait for MTA connections before 3440266059SGregory Neil Shapiro timing out (optional, see <a 3540266059SGregory Neil Shapiro href="smfi_settimeout.html">smfi_settimeout</a>). 3640266059SGregory Neil Shapiro</ul> 3740266059SGregory Neil Shapiro<p> 3840266059SGregory Neil ShapiroIf the filter fails to initialize libmilter, or if one or more of the 3940266059SGregory Neil Shapiroparameters it has passed are invalid, a subsequent call to smfi_main 4040266059SGregory Neil Shapirowill fail. 4140266059SGregory Neil Shapiro 4240266059SGregory Neil Shapiro<h2>Control flow</h2> 4340266059SGregory Neil Shapiro 4440266059SGregory Neil Shapiro<p> 4540266059SGregory Neil ShapiroThe following pseudocode describes the filtering process from the 4640266059SGregory Neil Shapiroperspective of a set of <code>N</code> MTA's, each corresponding to a 4740266059SGregory Neil Shapiroconnection. Callbacks are shown beside the processing stages in which 4840266059SGregory Neil Shapirothey are invoked; if no callbacks are defined for a particular stage, 4940266059SGregory Neil Shapirothat stage may be bypassed. Though it is not shown, processing may be 5040266059SGregory Neil Shapiroaborted at any time during a message, in which case the <a 5140266059SGregory Neil Shapirohref="xxfi_abort.html">xxfi_abort</a> callback is invoked and control 5240266059SGregory Neil Shapiroreturns to <code>MESSAGE</code>. 5340266059SGregory Neil Shapiro<p> 5440266059SGregory Neil Shapiro<pre> 5540266059SGregory Neil ShapiroFor each of N connections 5640266059SGregory Neil Shapiro{ 5740266059SGregory Neil Shapiro For each filter 5840266059SGregory Neil Shapiro process connection/helo (<a href="xxfi_connect.html">xxfi_connect</a>, <a href="xxfi_helo.html">xxfi_helo</a>) 5940266059SGregory Neil ShapiroMESSAGE:For each message in this connection (sequentially) 6040266059SGregory Neil Shapiro { 6140266059SGregory Neil Shapiro For each filter 6240266059SGregory Neil Shapiro process sender (<a href="xxfi_envfrom.html">xxfi_envfrom</a>) 6340266059SGregory Neil Shapiro For each recipient 6440266059SGregory Neil Shapiro { 6540266059SGregory Neil Shapiro For each filter 6640266059SGregory Neil Shapiro process recipient (<a href="xxfi_envrcpt.html">xxfi_envrcpt</a>) 6740266059SGregory Neil Shapiro } 6840266059SGregory Neil Shapiro For each filter 6940266059SGregory Neil Shapiro { 7040266059SGregory Neil Shapiro For each header 7140266059SGregory Neil Shapiro process header (<a href="xxfi_header.html">xxfi_header</a>) 7240266059SGregory Neil Shapiro process end of headers (<a href="xxfi_eoh.html">xxfi_eoh</a>) 7340266059SGregory Neil Shapiro For each body block 7440266059SGregory Neil Shapiro process this body block (<a href="xxfi_body.html">xxfi_body</a>) 7540266059SGregory Neil Shapiro process end of message (<a href="xxfi_eom.html">xxfi_eom</a>) 7640266059SGregory Neil Shapiro } 7740266059SGregory Neil Shapiro } 7840266059SGregory Neil Shapiro For each filter 7940266059SGregory Neil Shapiro process end of connection (<a href="xxfi_close.html">xxfi_close</a>) 8040266059SGregory Neil Shapiro} 8140266059SGregory Neil Shapiro</pre> 8240266059SGregory Neil Shapiro 8340266059SGregory Neil Shapiro<P>Note: Filters are contacted in order defined in config file.</P> 8440266059SGregory Neil Shapiro 8540266059SGregory Neil Shapiro<P> 8640266059SGregory Neil ShapiroTo write a filter, a vendor supplies callbacks to process relevant 8740266059SGregory Neil Shapiroparts of a message transaction. The library then controls all 8840266059SGregory Neil Shapirosequencing, threading, and protocol exchange with the MTA. <a 8940266059SGregory Neil Shapirohref="#figure-3">Figure 3</a> outlines control flow for a filter 9040266059SGregory Neil Shapiroprocess, showing where different callbacks are invoked. 9140266059SGregory Neil Shapiro</p> 9240266059SGregory Neil Shapiro<div align="center"><a name="figure-3"></a> 9340266059SGregory Neil Shapiro<table border=1 cellspacing=0 cellpadding=2 width="70%"> 9440266059SGregory Neil Shapiro<tr bgcolor="#dddddd"><th>SMTP Commands</th><th>Milter Callbacks</th></tr> 9540266059SGregory Neil Shapiro<tr><td>(open SMTP connection)</td><td>xxfi_connect</td></tr> 9640266059SGregory Neil Shapiro<tr><td>HELO ...</td><td>xxfi_helo</td></tr> 9740266059SGregory Neil Shapiro<tr><td>MAIL From: ...</td><td>xxfi_envfrom</td></tr> 9840266059SGregory Neil Shapiro<tr><td>RCPT To: ...</td><td>xxfi_envrcpt</td></tr> 9940266059SGregory Neil Shapiro<tr><td>[more RCPTs]</td><td>[xxfi_envrcpt]</td></tr> 10040266059SGregory Neil Shapiro<tr><td>DATA</td><td> </td></tr> 10140266059SGregory Neil Shapiro<tr><td>Header: ...</td><td>xxfi_header</td></tr> 10240266059SGregory Neil Shapiro<tr><td>[more headers]</td><td>[xxfi_header]</td></tr> 10340266059SGregory Neil Shapiro<tr><td> </td><td>xxfi_eoh</td></tr> 10440266059SGregory Neil Shapiro<tr><td>body... </td><td>xxfi_body</td></tr> 10540266059SGregory Neil Shapiro<tr><td>[more body...]</td><td>[xxfi_body]</td></tr> 10640266059SGregory Neil Shapiro<tr><td>.</td><td>xxfi_eom</td></tr> 10740266059SGregory Neil Shapiro<tr><td>QUIT</td><td>xxfi_close</td></tr> 10840266059SGregory Neil Shapiro<tr><td>(close SMTP connection)</td><td> </td></tr> 10940266059SGregory Neil Shapiro</table> 11040266059SGregory Neil Shapiro<b>Figure 3: Milter callbacks related to an SMTP transaction.</b> 11140266059SGregory Neil Shapiro</div> 11240266059SGregory Neil Shapiro<p> 11340266059SGregory Neil ShapiroNote that although only a single message is shown above, multiple 11440266059SGregory Neil Shapiromessages may be sent in a single connection. Note also that a message 11540266059SGregory Neil Shapiroand/or connection may be aborted by either the remote host or the MTA 11640266059SGregory Neil Shapiroat any point during the SMTP transaction. If this occurs during a 11740266059SGregory Neil Shapiromessage (between the MAIL command and the final "."), the filter's <a 11840266059SGregory Neil Shapirohref="xxfi_abort.html">xxfi_abort</a> routine will be called. <a 11940266059SGregory Neil Shapirohref="xxfi_close.html">xxfi_close</a> is called any time the 12040266059SGregory Neil Shapiroconnection closes. 12140266059SGregory Neil Shapiro 12240266059SGregory Neil Shapiro<h2>Multithreading</h2> 12340266059SGregory Neil Shapiro 12440266059SGregory Neil Shapiro<p> 12540266059SGregory Neil ShapiroA single filter process may handle any number of connections 12640266059SGregory Neil Shapirosimultaneously. All filtering callbacks must therefore be reentrant, 12740266059SGregory Neil Shapiroand use some appropriate external synchronization methods to access 12840266059SGregory Neil Shapiroglobal data. Furthermore, since there is not a one-to-one 12940266059SGregory Neil Shapirocorrespondence between threads and connections (N connections mapped 13040266059SGregory Neil Shapiroonto M threads, M <= N), connection-specific data must be accessed 13140266059SGregory Neil Shapirothrough the handles provided by the Milter library. The programmer 13240266059SGregory Neil Shapirocannot rely on library-supplied thread-specific data blocks 13340266059SGregory Neil Shapiro(e.g. pthread_getspecific()) to store connection-specific data. See 13440266059SGregory Neil Shapirothe API documentation for <a 13540266059SGregory Neil Shapirohref="smfi_setpriv.html">smfi_setpriv</a> and <a 13640266059SGregory Neil Shapirohref="smfi_getpriv.html">smfi_getpriv</a> for details. 13740266059SGregory Neil Shapiro 13840266059SGregory Neil Shapiro<h2>Resource management</h2> 13940266059SGregory Neil Shapiro 14040266059SGregory Neil ShapiroSince filters are likely to be long-lived, and to handle many 14140266059SGregory Neil Shapiroconnections, proper deallocation of per-connection resources is 14240266059SGregory Neil Shapiroimportant. The lifetime of a connection is bracketed by calls to the 14340266059SGregory Neil Shapirocallbacks <a href="xxfi_connect.html">xxfi_connect</a> and <a 14440266059SGregory Neil Shapirohref="xxfi_close.html">xxfi_close</a>. Therefore connection-specific 14540266059SGregory Neil Shapiroresources (accessed via <a href="smfi_getpriv.html">smfi_getpriv</a> 14640266059SGregory Neil Shapiroand <a href="smfi_setpriv.html">smfi_setpriv</a>) may be allocated in 14740266059SGregory Neil Shapiro<a href="xxfi_connect.html">xxfi_connect</a>, and should be freed in 14840266059SGregory Neil Shapiro<a href="xxfi_close.html">xxfi_close</a>. For further information see 14940266059SGregory Neil Shapirothe <a href="api.html#conn-msg">discussion</a> of message- versus 15040266059SGregory Neil Shapiroconnection-oriented routines. In particular, note that there is only 15140266059SGregory Neil Shapiroone connection-specific data pointer per connection. 15240266059SGregory Neil Shapiro<p> 15340266059SGregory Neil Shapiro 15440266059SGregory Neil ShapiroEach message is bracketed by calls to <a 15540266059SGregory Neil Shapirohref="xxfi_envfrom.html">xxfi_envfrom</a> and <a 15640266059SGregory Neil Shapirohref="xxfi_eom.html">xxfi_eom</a> (or <a 15740266059SGregory Neil Shapirohref="xxfi_abort.html">xxfi_abort</a>), implying that message-specific 15840266059SGregory Neil Shapiroresources can be allocated and reclaimed in these routines. Since the 15940266059SGregory Neil Shapiromessages in a connection are processed sequentially by each filter, 16040266059SGregory Neil Shapirothere will be only one active message associated with a given 16140266059SGregory Neil Shapiroconnection and filter (and connection-private data block). These 16240266059SGregory Neil Shapiroresources must still be accessed through <a 16340266059SGregory Neil Shapirohref="smfi_getpriv.html">smfi_getpriv</a> and <a 16440266059SGregory Neil Shapirohref="smfi_setpriv.html">smfi_setpriv</a>, and must be reclaimed 16540266059SGregory Neil Shapiroin <a href="xxfi_abort.html">xxfi_abort</a>. 16640266059SGregory Neil Shapiro 16740266059SGregory Neil Shapiro<h2>Signal Handling</h2> 16840266059SGregory Neil Shapiro 16940266059SGregory Neil Shapirolibmilter takes care of signal handling, the filters are 17040266059SGregory Neil Shapironot influenced directly by signals. 17140266059SGregory Neil ShapiroThere are basically two types of signal handlers: 17240266059SGregory Neil Shapiro 17340266059SGregory Neil Shapiro<ol> 17440266059SGregory Neil Shapiro<li><TT>Stop</TT>: no new connections from the MTA will be accepted, 17540266059SGregory Neil Shapirobut existing connections are allowed to continue. 17640266059SGregory Neil Shapiro<li><TT>Abort</TT>: all filters will be stopped as soon as the next 17740266059SGregory Neil Shapirocommunication with the MTA happens. 17840266059SGregory Neil Shapiro</ol> 17940266059SGregory Neil Shapiro 18040266059SGregory Neil ShapiroFilters are not terminated asynchronously (except by 18140266059SGregory Neil Shapirosignals that can't be caught). 18240266059SGregory Neil ShapiroIn the case of <TT>Abort</TT> the 18340266059SGregory Neil Shapiro<a href="xxfi_abort.html">xxfi_abort</a> callback is invoked. 18440266059SGregory Neil Shapiro 18540266059SGregory Neil Shapiro<hr size="1"> 18640266059SGregory Neil Shapiro<font size="-1"> 18740266059SGregory Neil ShapiroCopyright (c) 2000, 2001 Sendmail, Inc. and its suppliers. 18840266059SGregory Neil ShapiroAll rights reserved. 18940266059SGregory Neil Shapiro<br> 19040266059SGregory Neil ShapiroBy using this file, you agree to the terms and conditions set 19140266059SGregory Neil Shapiroforth in the <a href="LICENSE.txt">LICENSE</a>. 19240266059SGregory Neil Shapiro</font> 19340266059SGregory Neil Shapiro</body> 19440266059SGregory Neil Shapiro</html> 195