1168515Sgshapiro<HTML>
2168515Sgshapiro<HEAD><TITLE>Installation and Configuration</TITLE>
3168515Sgshapiro</HEAD>
4168515Sgshapiro<BODY>
5132943Sgshapiro<!--
6266711Sgshapiro$Id: installation.html,v 1.24 2013-11-22 20:51:39 ca Exp $
7132943Sgshapiro-->
8168515Sgshapiro<H1>Installation</H1>
9168515Sgshapiro<H2>Contents</H2>
10168515Sgshapiro<UL>
11168515Sgshapiro    <LI><A href="#compile">Compiling and Installing Your Filter</A>
12168515Sgshapiro    <LI><A href="#config">Configuring Sendmail</A>
13168515Sgshapiro</UL>
1490792Sgshapiro
15168515Sgshapiro<H2><A name="compile">Compiling and Installing Your Filter</A></H2>
1690792Sgshapiro
1790792SgshapiroTo compile a filter, modify the Makefile provided with the sample program, or:
18168515Sgshapiro<UL>
19168515Sgshapiro    <LI>Put the include and Sendmail directories in your include path
2090792Sgshapiro    (e.g. -I/path/to/include -I/path/to/sendmail).  
2190792Sgshapiro
22168515Sgshapiro    <LI>Make sure libmilter.a is in your library path, and link your
2390792Sgshapiro    application with it (e.g. "-lmilter").
2490792Sgshapiro
25168515Sgshapiro    <LI>Compile with pthreads, either by using -pthread for gcc, or
2690792Sgshapiro    linking with a pthreads support library (-lpthread).
27168515Sgshapiro</UL>
2890792SgshapiroYour compile command line will look like
29168515Sgshapiro<PRE>
3090792Sgshapirocc -I/path/to/include -I/path/to/sendmail -c myfile.c
31168515Sgshapiro</PRE>
3290792Sgshapiroand your linking command line will look something like
33168515Sgshapiro<PRE>
3490792Sgshapirocc -o myfilter [object-files] -L[library-location] -lmilter -pthread
35168515Sgshapiro</PRE>
3690792Sgshapiro
37168515Sgshapiro<H2><A name="config">Configuring Sendmail</A></H2>
3890792Sgshapiro
39168515SgshapiroIf you use a sendmail version older than 8.13 please see
4094334Sgshapirothe instructions for your version.
41168515SgshapiroThe default compilation options for sendmail enable support
42168515Sgshapirofor milters since 8.13.
4390792Sgshapiro
4490792Sgshapiro<P>
4590792SgshapiroNext, you must add the desired filters to your sendmail configuration
4694334Sgshapiro(.mc) file.
4794334SgshapiroMail filters have three equates:
48168515SgshapiroThe required <CODE>S=</CODE> equate specifies the socket where
49168515Sgshapirosendmail should look for the filter; the optional <CODE>F=</CODE> and
50168515Sgshapiro<CODE>T=</CODE> equates specify flags and timeouts, respectively.
51168515SgshapiroAll equates names, equate field names, and flag values are case sensitive.
5290792Sgshapiro
5390792Sgshapiro<P>
54168515SgshapiroThe current flags (<CODE>F=</CODE>) are:
55168515Sgshapiro<P>
56168515Sgshapiro<TABLE cellspacing="1" cellpadding=4 border=1>
57168515Sgshapiro<TR bgcolor="#dddddd" align=left valign=top>
58168515Sgshapiro<TH>Flag</TH>   <TH align="center">Meaning</TH>
5990792Sgshapiro</TR>
60168515Sgshapiro<TR align="left" valign=top>
6190792Sgshapiro<TD>R</TD>      <TD>Reject connection if filter unavailable</TD>
6290792Sgshapiro</TR>
63168515Sgshapiro<TR align="left" valign=top>
6490792Sgshapiro<TD>T</TD>      <TD>Temporary fail connection if filter unavailable</TD>
6590792Sgshapiro</TR>
6690792Sgshapiro</TABLE>
6790792Sgshapiro
6890792SgshapiroIf a filter is unavailable or unresponsive and no flags have been
6990792Sgshapirospecified, the MTA will continue normal handling of the current
7090792Sgshapiroconnection.
71168515SgshapiroThe MTA will try to contact the filter again on each new connection.
7290792Sgshapiro
7390792Sgshapiro<P>
74168515SgshapiroThere are three fields inside of the <CODE>T=</CODE> equate: S, R, and E.
75168515SgshapiroNote the separator between each is a ";" (semicolon), as ","
76168515Sgshapiro(comma) already separates equates.
77168515SgshapiroThe value of each field is a decimal number followed by a single letter
78168515Sgshapirodesignating the units ("s" for seconds, "m" for minutes).
79168515SgshapiroThe fields have the following meanings:
80168515Sgshapiro<P>
8190792Sgshapiro<TABLE cellspacing="1" cellpadding=4 border=1>
8290792Sgshapiro<TR bgcolor="#dddddd" align=left valign=top>
8390792Sgshapiro<TH>Flag</TH>   <TH align="center">Meaning</TH>
8490792Sgshapiro</TR>
8590792Sgshapiro<TR align="left" valign=top>
8690792Sgshapiro<TD>C</TD>      <TD>Timeout for connecting to a filter.  If set to 0, the
87168515Sgshapiro		system's <CODE>connect(2)</CODE> timeout will be used.
8890792Sgshapiro		Default: 5m</TD>
8990792Sgshapiro</TR>
9090792Sgshapiro<TR align="left" valign=top>
9190792Sgshapiro<TD>S</TD>      <TD>Timeout for sending information from the MTA to a
9290792Sgshapiro                filter.  Default: 10s</TD>
9390792Sgshapiro</TR>
9490792Sgshapiro<TR align="left" valign=top>
9590792Sgshapiro<TD>R</TD>      <TD>Timeout for reading reply from the filter.  Default: 10s</TD>
9690792Sgshapiro</TR>
9790792Sgshapiro<TR align="left" valign=top>
9890792Sgshapiro<TD>E</TD>      <TD>Overall timeout between sending end-of-message to
9990792Sgshapiro                filter and waiting for the final acknowledgment.  Default: 5m</TD>
10090792Sgshapiro</TR>
10190792Sgshapiro</TABLE>
10290792Sgshapiro
103168515Sgshapiro<P>
104168515SgshapiroThe following sendmail.mc example specifies three filters.
105168515SgshapiroThe first two rendezvous on Unix-domain sockets in the /var/run directory;
106168515Sgshapirothe third uses an IP socket on port 999.
107168515Sgshapiro<PRE>
10890792Sgshapiro	INPUT_MAIL_FILTER(`filter1', `S=unix:/var/run/f1.sock, F=R')
10990792Sgshapiro	INPUT_MAIL_FILTER(`filter2', `S=unix:/var/run/f2.sock, F=T, T=S:1s;R:1s;E:5m')
11090792Sgshapiro	INPUT_MAIL_FILTER(`filter3', `S=inet:999@localhost, T=C:2m')
11190792Sgshapiro
11290792Sgshapiro	define(`confINPUT_MAIL_FILTERS', `filter2,filter1,filter3')
113168515Sgshapiro<HR width="30%">
11494334Sgshapiro	m4 ../m4/cf.m4 myconfig.mc &gt; myconfig.cf
115168515Sgshapiro</PRE>
11690792SgshapiroBy default, the filters would be run in the order declared,
11790792Sgshapiroi.e. "filter1, filter2, filter3"; however, since
118168515Sgshapiro<CODE>confINPUT_MAIL_FILTERS</CODE> is defined, the filters will be
119168515Sgshapirorun "filter2, filter1, filter3".
120168515SgshapiroAlso note that a filter can be defined
121168515Sgshapirowithout adding it to the input filter list by using
12290792SgshapiroMAIL_FILTER() instead of INPUT_MAIL_FILTER().
12390792Sgshapiro
124168515Sgshapiro<P>
12590792SgshapiroThe above macros will result in the following lines being added to
12690792Sgshapiroyour .cf file:
12790792Sgshapiro<PRE>
12890792Sgshapiro        Xfilter1, S=unix:/var/run/f1.sock, F=R
12990792Sgshapiro        Xfilter2, S=unix:/var/run/f2.sock, F=T, T=S:1s;R:1s;E:5m
13090792Sgshapiro        Xfilter3, S=inet:999@localhost, T=C:2m
13190792Sgshapiro
13290792Sgshapiro        O InputMailFilters=filter2,filter1,filter3
13390792Sgshapiro</PRE>
134168515Sgshapiro<P>
135168515SgshapiroFinally, the sendmail macros accessible via
136168515Sgshapiro<A HREF="smfi_getsymval.html">smfi_getsymval</A> can be configured by
13790792Sgshapirodefining the following m4 variables (or cf options):
138168515Sgshapiro<TABLE cellspacing="1" cellpadding=4 border=1>
139168515Sgshapiro<TR bgcolor="#dddddd" align=left valign=top>
140168515Sgshapiro<TH align="center">In .mc file</TH>   <TH align="center">In .cf file</TH>
141168515Sgshapiro<TH align="center">Default Value</TH>
142168515Sgshapiro</TR>
143168515Sgshapiro<TR><TD>confMILTER_MACROS_CONNECT</TD><TD>Milter.macros.connect</TD>
144168515Sgshapiro<TD><CODE>j, _, {daemon_name}, {if_name}, {if_addr}</CODE></TD></TR>
145168515Sgshapiro<TR><TD>confMILTER_MACROS_HELO</TD><TD>Milter.macros.helo</TD>
146168515Sgshapiro<TD><CODE>{tls_version}, {cipher}, {cipher_bits}, {cert_subject},
147168515Sgshapiro{cert_issuer}</CODE></TD></TR>
148168515Sgshapiro<TR><TD>confMILTER_MACROS_ENVFROM</TD><TD>Milter.macros.envfrom</TD>
149168515Sgshapiro<TD><CODE>i, {auth_type}, {auth_authen}, {auth_ssf}, {auth_author},
150168515Sgshapiro{mail_mailer}, {mail_host}, {mail_addr}</CODE></TD></TR>
151168515Sgshapiro<TR><TD>confMILTER_MACROS_ENVRCPT</TD><TD>Milter.macros.envrcpt</TD>
152168515Sgshapiro<TD><CODE>{rcpt_mailer}, {rcpt_host}, {rcpt_addr}</CODE></TD></TR>
153168515Sgshapiro</TABLE>
15490792SgshapiroFor information about available macros and their meanings, please
15590792Sgshapiroconsult the sendmail documentation.
156168515Sgshapiro<HR size="1">
157168515Sgshapiro<FONT size="-1">
158261370SgshapiroCopyright (c) 2000-2003, 2006 Proofpoint, Inc. and its suppliers.
15990792SgshapiroAll rights reserved.
160168515Sgshapiro<BR>
16190792SgshapiroBy using this file, you agree to the terms and conditions set
162112810Sgshapiroforth in the LICENSE.
163168515Sgshapiro</FONT>
164168515Sgshapiro</BODY>
165168515Sgshapiro</HTML>
166