1<html>
2<head><title>Installation and Configuration</title>
3</head>
4<body>
5<!--
6$Id: installation.html,v 1.20 2003/03/05 19:57:54 ca Exp $
7-->
8<h1>Installation</h1>
9<h2>Contents</h2>
10<ul>
11    <li><a href="#compile">Compiling and Installing Your Filter</a>
12    <li><a href="#config">Configuring Sendmail</a>
13</ul>
14
15<h2><a name="compile">Compiling and Installing Your Filter</A></h2>
16
17To compile a filter, modify the Makefile provided with the sample program, or:
18<ul>
19    <li>Put the include and Sendmail directories in your include path
20    (e.g. -I/path/to/include -I/path/to/sendmail).
21
22    <li>Make sure libmilter.a is in your library path, and link your
23    application with it (e.g. "-lmilter").
24
25    <li>Compile with pthreads, either by using -pthread for gcc, or
26    linking with a pthreads support library (-lpthread).
27</ul>
28Your compile command line will look like
29<pre>
30cc -I/path/to/include -I/path/to/sendmail -c myfile.c
31</pre>
32and your linking command line will look something like
33<pre>
34cc -o myfilter [object-files] -L[library-location] -lmilter -pthread
35</pre>
36
37<H2><a name="config">Configuring Sendmail</A></H2>
38
39First, you must compile sendmail with MILTER defined.
40If you use a sendmail version older than 8.12 please see
41the instructions for your version.
42To do this, add the following lines to your build
43configuration file (devtools/Site/config.site.m4)
44<pre>
45APPENDDEF(`conf_sendmail_ENVDEF', `-DMILTER')
46</pre>
47
48then type <code>./Build -c</code> in your sendmail directory.
49
50<P>
51Next, you must add the desired filters to your sendmail configuration
52(.mc) file.
53Mail filters have three equates:
54The required <code>S=</code> equate specifies the socket where
55sendmail should look for the filter; The optional <code>F=</code> and
56<code>T=</code> equates specify flags and timeouts, respectively.  All
57equates names, equate field names, and flag values are case sensitive.
58
59<P>
60The current flags (<code>F=</code>) are:
61<p>
62<table cellspacing="1" cellpadding=4 border=1>
63<tr bgcolor="#dddddd" align=left valign=top>
64<th>Flag</TH>   <th align="center">Meaning</TH>
65</TR>
66<tr align="left" valign=top>
67<TD>R</TD>      <TD>Reject connection if filter unavailable</TD>
68</TR>
69<tr align="left" valign=top>
70<TD>T</TD>      <TD>Temporary fail connection if filter unavailable</TD>
71</TR>
72</TABLE>
73
74If a filter is unavailable or unresponsive and no flags have been
75specified, the MTA will continue normal handling of the current
76connection.  The MTA will try to contact the filter again on each new
77connection.
78
79<P>
80There are three fields inside of the <code>T=</code> equate: S, R, and
81E.  Note the separator between each is a ";" (semicolon), as ","
82(comma) already separates equates.  The value of each field is a
83decimal number followed by a single letter designating the units ("s"
84for seconds, "m" for minutes).  The fields have the following
85meanings:
86<p>
87<TABLE cellspacing="1" cellpadding=4 border=1>
88<TR bgcolor="#dddddd" align=left valign=top>
89<TH>Flag</TH>   <TH align="center">Meaning</TH>
90</TR>
91<TR align="left" valign=top>
92<TD>C</TD>      <TD>Timeout for connecting to a filter.  If set to 0, the
93		system's <CODE>connect()</CODE> timeout will be used.
94		Default: 5m</TD>
95</TR>
96<TR align="left" valign=top>
97<TD>S</TD>      <TD>Timeout for sending information from the MTA to a
98                filter.  Default: 10s</TD>
99</TR>
100<TR align="left" valign=top>
101<TD>R</TD>      <TD>Timeout for reading reply from the filter.  Default: 10s</TD>
102</TR>
103<TR align="left" valign=top>
104<TD>E</TD>      <TD>Overall timeout between sending end-of-message to
105                filter and waiting for the final acknowledgment.  Default: 5m</TD>
106</TR>
107</TABLE>
108
109<p>
110The following sendmail.mc example specifies three filters.  The first
111two rendezvous on Unix-domain sockets in the /var/run directory; the
112third uses an IP socket on port 999.
113<pre>
114	INPUT_MAIL_FILTER(`filter1', `S=unix:/var/run/f1.sock, F=R')
115	INPUT_MAIL_FILTER(`filter2', `S=unix:/var/run/f2.sock, F=T, T=S:1s;R:1s;E:5m')
116	INPUT_MAIL_FILTER(`filter3', `S=inet:999@localhost, T=C:2m')
117
118	define(`confINPUT_MAIL_FILTERS', `filter2,filter1,filter3')
119<hr width="30%">
120	m4 ../m4/cf.m4 myconfig.mc &gt; myconfig.cf
121</pre>
122By default, the filters would be run in the order declared,
123i.e. "filter1, filter2, filter3"; however, since
124<code>confINPUT_MAIL_FILTERS</code> is defined, the filters will be
125run "filter2, filter1, filter3".  Also note that a filter can be
126defined without adding it to the input filter list by using
127MAIL_FILTER() instead of INPUT_MAIL_FILTER().
128
129<p>
130The above macros will result in the following lines being added to
131your .cf file:
132<PRE>
133        Xfilter1, S=unix:/var/run/f1.sock, F=R
134        Xfilter2, S=unix:/var/run/f2.sock, F=T, T=S:1s;R:1s;E:5m
135        Xfilter3, S=inet:999@localhost, T=C:2m
136
137        O InputMailFilters=filter2,filter1,filter3
138</PRE>
139<p>
140Finally, the sendmail macros accessible via <a
141href="smfi_getsymval.html">smfi_getsymval</a> can be configured by
142defining the following m4 variables (or cf options):
143<table cellspacing="1" cellpadding=4 border=1>
144<tr bgcolor="#dddddd" align=left valign=top>
145<th align="center">In .mc file</th>   <th align="center">In .cf file</TH>
146<th align="center">Default Value</th>
147</tr>
148<tr><td>confMILTER_MACROS_CONNECT</td><td>Milter.macros.connect</td>
149<td><code>j, _, {daemon_name}, {if_name}, {if_addr}</code></td></tr>
150<tr><td>confMILTER_MACROS_HELO</td><td>Milter.macros.helo</td>
151<td><code>{tls_version}, {cipher}, {cipher_bits}, {cert_subject},
152{cert_issuer}</code></td></tr>
153<tr><td>confMILTER_MACROS_ENVFROM</td><td>Milter.macros.envfrom</td>
154<td><code>i, {auth_type}, {auth_authen}, {auth_ssf}, {auth_author},
155{mail_mailer}, {mail_host}, {mail_addr}</code></td></tr>
156<tr><td>confMILTER_MACROS_ENVRCPT</td><td>Milter.macros.envrcpt</td>
157<td><code>{rcpt_mailer}, {rcpt_host}, {rcpt_addr}</code></td></tr>
158</table>
159For information about available macros and their meanings, please
160consult the sendmail documentation.
161<hr size="1">
162<font size="-1">
163Copyright (c) 2000-2003 Sendmail, Inc. and its suppliers.
164All rights reserved.
165<br>
166By using this file, you agree to the terms and conditions set
167forth in the LICENSE.
168</font>
169</body> </html>
170