1<HTML> 2<HEAD><TITLE>Installation and Configuration</TITLE> 3</HEAD> 4<BODY> 5<!-- 6$Id: installation.html,v 1.24 2013-11-22 20:51:39 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 39If you use a sendmail version older than 8.13 please see 40the instructions for your version. 41The default compilation options for sendmail enable support 42for milters since 8.13. 43 44<P> 45Next, you must add the desired filters to your sendmail configuration 46(.mc) file. 47Mail filters have three equates: 48The required <CODE>S=</CODE> equate specifies the socket where 49sendmail should look for the filter; the optional <CODE>F=</CODE> and 50<CODE>T=</CODE> equates specify flags and timeouts, respectively. 51All equates names, equate field names, and flag values are case sensitive. 52 53<P> 54The current flags (<CODE>F=</CODE>) are: 55<P> 56<TABLE cellspacing="1" cellpadding=4 border=1> 57<TR bgcolor="#dddddd" align=left valign=top> 58<TH>Flag</TH> <TH align="center">Meaning</TH> 59</TR> 60<TR align="left" valign=top> 61<TD>R</TD> <TD>Reject connection if filter unavailable</TD> 62</TR> 63<TR align="left" valign=top> 64<TD>T</TD> <TD>Temporary fail connection if filter unavailable</TD> 65</TR> 66</TABLE> 67 68If a filter is unavailable or unresponsive and no flags have been 69specified, the MTA will continue normal handling of the current 70connection. 71The MTA will try to contact the filter again on each new connection. 72 73<P> 74There are three fields inside of the <CODE>T=</CODE> equate: S, R, and E. 75Note the separator between each is a ";" (semicolon), as "," 76(comma) already separates equates. 77The value of each field is a decimal number followed by a single letter 78designating the units ("s" for seconds, "m" for minutes). 79The fields have the following meanings: 80<P> 81<TABLE cellspacing="1" cellpadding=4 border=1> 82<TR bgcolor="#dddddd" align=left valign=top> 83<TH>Flag</TH> <TH align="center">Meaning</TH> 84</TR> 85<TR align="left" valign=top> 86<TD>C</TD> <TD>Timeout for connecting to a filter. If set to 0, the 87 system's <CODE>connect(2)</CODE> timeout will be used. 88 Default: 5m</TD> 89</TR> 90<TR align="left" valign=top> 91<TD>S</TD> <TD>Timeout for sending information from the MTA to a 92 filter. Default: 10s</TD> 93</TR> 94<TR align="left" valign=top> 95<TD>R</TD> <TD>Timeout for reading reply from the filter. Default: 10s</TD> 96</TR> 97<TR align="left" valign=top> 98<TD>E</TD> <TD>Overall timeout between sending end-of-message to 99 filter and waiting for the final acknowledgment. Default: 5m</TD> 100</TR> 101</TABLE> 102 103<P> 104The following sendmail.mc example specifies three filters. 105The first two rendezvous on Unix-domain sockets in the /var/run directory; 106the third uses an IP socket on port 999. 107<PRE> 108 INPUT_MAIL_FILTER(`filter1', `S=unix:/var/run/f1.sock, F=R') 109 INPUT_MAIL_FILTER(`filter2', `S=unix:/var/run/f2.sock, F=T, T=S:1s;R:1s;E:5m') 110 INPUT_MAIL_FILTER(`filter3', `S=inet:999@localhost, T=C:2m') 111 112 define(`confINPUT_MAIL_FILTERS', `filter2,filter1,filter3') 113<HR width="30%"> 114 m4 ../m4/cf.m4 myconfig.mc > myconfig.cf 115</PRE> 116By default, the filters would be run in the order declared, 117i.e. "filter1, filter2, filter3"; however, since 118<CODE>confINPUT_MAIL_FILTERS</CODE> is defined, the filters will be 119run "filter2, filter1, filter3". 120Also note that a filter can be defined 121without adding it to the input filter list by using 122MAIL_FILTER() instead of INPUT_MAIL_FILTER(). 123 124<P> 125The above macros will result in the following lines being added to 126your .cf file: 127<PRE> 128 Xfilter1, S=unix:/var/run/f1.sock, F=R 129 Xfilter2, S=unix:/var/run/f2.sock, F=T, T=S:1s;R:1s;E:5m 130 Xfilter3, S=inet:999@localhost, T=C:2m 131 132 O InputMailFilters=filter2,filter1,filter3 133</PRE> 134<P> 135Finally, the sendmail macros accessible via 136<A HREF="smfi_getsymval.html">smfi_getsymval</A> can be configured by 137defining the following m4 variables (or cf options): 138<TABLE cellspacing="1" cellpadding=4 border=1> 139<TR bgcolor="#dddddd" align=left valign=top> 140<TH align="center">In .mc file</TH> <TH align="center">In .cf file</TH> 141<TH align="center">Default Value</TH> 142</TR> 143<TR><TD>confMILTER_MACROS_CONNECT</TD><TD>Milter.macros.connect</TD> 144<TD><CODE>j, _, {daemon_name}, {if_name}, {if_addr}</CODE></TD></TR> 145<TR><TD>confMILTER_MACROS_HELO</TD><TD>Milter.macros.helo</TD> 146<TD><CODE>{tls_version}, {cipher}, {cipher_bits}, {cert_subject}, 147{cert_issuer}</CODE></TD></TR> 148<TR><TD>confMILTER_MACROS_ENVFROM</TD><TD>Milter.macros.envfrom</TD> 149<TD><CODE>i, {auth_type}, {auth_authen}, {auth_ssf}, {auth_author}, 150{mail_mailer}, {mail_host}, {mail_addr}</CODE></TD></TR> 151<TR><TD>confMILTER_MACROS_ENVRCPT</TD><TD>Milter.macros.envrcpt</TD> 152<TD><CODE>{rcpt_mailer}, {rcpt_host}, {rcpt_addr}</CODE></TD></TR> 153</TABLE> 154For information about available macros and their meanings, please 155consult the sendmail documentation. 156<HR size="1"> 157<FONT size="-1"> 158Copyright (c) 2000-2003, 2006 Proofpoint, Inc. and its suppliers. 159All rights reserved. 160<BR> 161By using this file, you agree to the terms and conditions set 162forth in the LICENSE. 163</FONT> 164</BODY> 165</HTML> 166