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