xref: /freebsd/contrib/sendmail/libmilter/docs/installation.html (revision 5ef517c097100c80269c8a0e02678a89fde6b35e)
140266059SGregory Neil Shapiro<html>
240266059SGregory Neil Shapiro<head><title>Installation and Configuration</title>
340266059SGregory Neil Shapiro</head>
440266059SGregory Neil Shapiro<body>
540266059SGregory Neil Shapiro<h1>Installation</h1>
640266059SGregory Neil Shapiro<h2>Contents</h2>
740266059SGregory Neil Shapiro<ul>
840266059SGregory Neil Shapiro    <li><a href="#compile">Compiling and Installing Your Filter</a>
940266059SGregory Neil Shapiro    <li><a href="#config">Configuring Sendmail</a>
1040266059SGregory Neil Shapiro</ul>
1140266059SGregory Neil Shapiro
1240266059SGregory Neil Shapiro<h2><a name="compile">Compiling and Installing Your Filter</A></h2>
1340266059SGregory Neil Shapiro
1440266059SGregory Neil ShapiroTo compile a filter, modify the Makefile provided with the sample program, or:
1540266059SGregory Neil Shapiro<ul>
1640266059SGregory Neil Shapiro    <li>Put the include and Sendmail directories in your include path
1740266059SGregory Neil Shapiro    (e.g. -I/path/to/include -I/path/to/sendmail).
1840266059SGregory Neil Shapiro
195ef517c0SGregory Neil Shapiro    <li>Make sure libmilter.a is in your library path, and link your
2040266059SGregory Neil Shapiro    application with it (e.g. "-lmilter").
2140266059SGregory Neil Shapiro
2240266059SGregory Neil Shapiro    <li>Compile with pthreads, either by using -pthread for gcc, or
2340266059SGregory Neil Shapiro    linking with a pthreads support library (-lpthread).
2440266059SGregory Neil Shapiro</ul>
2540266059SGregory Neil ShapiroYour compile command line will look like
2640266059SGregory Neil Shapiro<pre>
2740266059SGregory Neil Shapirocc -I/path/to/include -I/path/to/sendmail -c myfile.c
2840266059SGregory Neil Shapiro</pre>
2940266059SGregory Neil Shapiroand your linking command line will look something like
3040266059SGregory Neil Shapiro<pre>
3140266059SGregory Neil Shapirocc -o myfilter [object-files] -L[library-location] -lmilter -pthread
3240266059SGregory Neil Shapiro</pre>
3340266059SGregory Neil Shapiro
3440266059SGregory Neil Shapiro<H2><a name="config">Configuring Sendmail</A></H2>
3540266059SGregory Neil Shapiro
36605302a5SGregory Neil ShapiroFirst, you must compile sendmail with MILTER defined.
37605302a5SGregory Neil ShapiroIf you use a sendmail version older than 8.12 please see
38605302a5SGregory Neil Shapirothe instructions for your version.
39605302a5SGregory Neil ShapiroTo do this, add the following lines to your build
4040266059SGregory Neil Shapiroconfiguration file (devtools/Site/config.site.m4)
4140266059SGregory Neil Shapiro<pre>
42605302a5SGregory Neil ShapiroAPPENDDEF(`conf_sendmail_ENVDEF', `-DMILTER')
4340266059SGregory Neil Shapiro</pre>
4440266059SGregory Neil Shapiro
4540266059SGregory Neil Shapirothen type <code>./Build -c</code> in your sendmail directory.
4640266059SGregory Neil Shapiro
4740266059SGregory Neil Shapiro<P>
4840266059SGregory Neil ShapiroNext, you must add the desired filters to your sendmail configuration
49605302a5SGregory Neil Shapiro(.mc) file.
50605302a5SGregory Neil ShapiroMail filters have three equates:
5140266059SGregory Neil ShapiroThe required <code>S=</code> equate specifies the socket where
5240266059SGregory Neil Shapirosendmail should look for the filter; The optional <code>F=</code> and
5340266059SGregory Neil Shapiro<code>T=</code> equates specify flags and timeouts, respectively.  All
5440266059SGregory Neil Shapiroequates names, equate field names, and flag values are case sensitive.
5540266059SGregory Neil Shapiro
5640266059SGregory Neil Shapiro<P>
5740266059SGregory Neil ShapiroThe current flags (<code>F=</code>) are:
5840266059SGregory Neil Shapiro<p>
5940266059SGregory Neil Shapiro<table cellspacing="1" cellpadding=4 border=1>
6040266059SGregory Neil Shapiro<tr bgcolor="#dddddd" align=left valign=top>
6140266059SGregory Neil Shapiro<th>Flag</TH>   <th align="center">Meaning</TH>
6240266059SGregory Neil Shapiro</TR>
6340266059SGregory Neil Shapiro<tr align="left" valign=top>
6440266059SGregory Neil Shapiro<TD>R</TD>      <TD>Reject connection if filter unavailable</TD>
6540266059SGregory Neil Shapiro</TR>
6640266059SGregory Neil Shapiro<tr align="left" valign=top>
6740266059SGregory Neil Shapiro<TD>T</TD>      <TD>Temporary fail connection if filter unavailable</TD>
6840266059SGregory Neil Shapiro</TR>
6940266059SGregory Neil Shapiro</TABLE>
7040266059SGregory Neil Shapiro
7140266059SGregory Neil ShapiroIf a filter is unavailable or unresponsive and no flags have been
7240266059SGregory Neil Shapirospecified, the MTA will continue normal handling of the current
7340266059SGregory Neil Shapiroconnection.  The MTA will try to contact the filter again on each new
7440266059SGregory Neil Shapiroconnection.
7540266059SGregory Neil Shapiro
7640266059SGregory Neil Shapiro<P>
7740266059SGregory Neil ShapiroThere are three fields inside of the <code>T=</code> equate: S, R, and
7840266059SGregory Neil ShapiroE.  Note the separator between each is a ";" (semicolon), as ","
7940266059SGregory Neil Shapiro(comma) already separates equates.  The value of each field is a
8040266059SGregory Neil Shapirodecimal number followed by a single letter designating the units ("s"
8140266059SGregory Neil Shapirofor seconds, "m" for minutes).  The fields have the following
8240266059SGregory Neil Shapiromeanings:
8340266059SGregory Neil Shapiro<p>
8440266059SGregory Neil Shapiro<TABLE cellspacing="1" cellpadding=4 border=1>
8540266059SGregory Neil Shapiro<TR bgcolor="#dddddd" align=left valign=top>
8640266059SGregory Neil Shapiro<TH>Flag</TH>   <TH align="center">Meaning</TH>
8740266059SGregory Neil Shapiro</TR>
8840266059SGregory Neil Shapiro<TR align="left" valign=top>
8940266059SGregory Neil Shapiro<TD>C</TD>      <TD>Timeout for connecting to a filter.  If set to 0, the
9040266059SGregory Neil Shapiro		system's <CODE>connect()</CODE> timeout will be used.
9140266059SGregory Neil Shapiro		Default: 5m</TD>
9240266059SGregory Neil Shapiro</TR>
9340266059SGregory Neil Shapiro<TR align="left" valign=top>
9440266059SGregory Neil Shapiro<TD>S</TD>      <TD>Timeout for sending information from the MTA to a
9540266059SGregory Neil Shapiro                filter.  Default: 10s</TD>
9640266059SGregory Neil Shapiro</TR>
9740266059SGregory Neil Shapiro<TR align="left" valign=top>
9840266059SGregory Neil Shapiro<TD>R</TD>      <TD>Timeout for reading reply from the filter.  Default: 10s</TD>
9940266059SGregory Neil Shapiro</TR>
10040266059SGregory Neil Shapiro<TR align="left" valign=top>
10140266059SGregory Neil Shapiro<TD>E</TD>      <TD>Overall timeout between sending end-of-message to
10240266059SGregory Neil Shapiro                filter and waiting for the final acknowledgment.  Default: 5m</TD>
10340266059SGregory Neil Shapiro</TR>
10440266059SGregory Neil Shapiro</TABLE>
10540266059SGregory Neil Shapiro
10640266059SGregory Neil Shapiro<p>
10740266059SGregory Neil ShapiroThe following sendmail.mc example specifies three filters.  The first
10840266059SGregory Neil Shapirotwo rendezvous on Unix-domain sockets in the /var/run directory; the
10940266059SGregory Neil Shapirothird uses an IP socket on port 999.
11040266059SGregory Neil Shapiro<pre>
11140266059SGregory Neil Shapiro	INPUT_MAIL_FILTER(`filter1', `S=unix:/var/run/f1.sock, F=R')
11240266059SGregory Neil Shapiro	INPUT_MAIL_FILTER(`filter2', `S=unix:/var/run/f2.sock, F=T, T=S:1s;R:1s;E:5m')
11340266059SGregory Neil Shapiro	INPUT_MAIL_FILTER(`filter3', `S=inet:999@localhost, T=C:2m')
11440266059SGregory Neil Shapiro
11540266059SGregory Neil Shapiro	define(`confINPUT_MAIL_FILTERS', `filter2,filter1,filter3')
11640266059SGregory Neil Shapiro<hr width="30%">
117605302a5SGregory Neil Shapiro	m4 ../m4/cf.m4 myconfig.mc &gt; myconfig.cf
11840266059SGregory Neil Shapiro</pre>
11940266059SGregory Neil ShapiroBy default, the filters would be run in the order declared,
12040266059SGregory Neil Shapiroi.e. "filter1, filter2, filter3"; however, since
12140266059SGregory Neil Shapiro<code>confINPUT_MAIL_FILTERS</code> is defined, the filters will be
12240266059SGregory Neil Shapirorun "filter2, filter1, filter3".  Also note that a filter can be
12340266059SGregory Neil Shapirodefined without adding it to the input filter list by using
12440266059SGregory Neil ShapiroMAIL_FILTER() instead of INPUT_MAIL_FILTER().
12540266059SGregory Neil Shapiro
12640266059SGregory Neil Shapiro<p>
12740266059SGregory Neil ShapiroThe above macros will result in the following lines being added to
12840266059SGregory Neil Shapiroyour .cf file:
12940266059SGregory Neil Shapiro<PRE>
13040266059SGregory Neil Shapiro        Xfilter1, S=unix:/var/run/f1.sock, F=R
13140266059SGregory Neil Shapiro        Xfilter2, S=unix:/var/run/f2.sock, F=T, T=S:1s;R:1s;E:5m
13240266059SGregory Neil Shapiro        Xfilter3, S=inet:999@localhost, T=C:2m
13340266059SGregory Neil Shapiro
13440266059SGregory Neil Shapiro        O InputMailFilters=filter2,filter1,filter3
13540266059SGregory Neil Shapiro</PRE>
13640266059SGregory Neil Shapiro<p>
13740266059SGregory Neil ShapiroFinally, the sendmail macros accessible via <a
13840266059SGregory Neil Shapirohref="smfi_getsymval.html">smfi_getsymval</a> can be configured by
13940266059SGregory Neil Shapirodefining the following m4 variables (or cf options):
14040266059SGregory Neil Shapiro<table cellspacing="1" cellpadding=4 border=1>
14140266059SGregory Neil Shapiro<tr bgcolor="#dddddd" align=left valign=top>
14240266059SGregory Neil Shapiro<th align="center">In .mc file</th>   <th align="center">In .cf file</TH>
14340266059SGregory Neil Shapiro<th align="center">Default Value</th>
14440266059SGregory Neil Shapiro</tr>
14540266059SGregory Neil Shapiro<tr><td>confMILTER_MACROS_CONNECT</td><td>Milter.macros.connect</td>
14640266059SGregory Neil Shapiro<td><code>j, _, {daemon_name}, {if_name}, {if_addr}</code></td></tr>
14740266059SGregory Neil Shapiro<tr><td>confMILTER_MACROS_HELO</td><td>Milter.macros.helo</td>
14840266059SGregory Neil Shapiro<td><code>{tls_version}, {cipher}, {cipher_bits}, {cert_subject},
14940266059SGregory Neil Shapiro{cert_issuer}</code></td></tr>
15040266059SGregory Neil Shapiro<tr><td>confMILTER_MACROS_ENVFROM</td><td>Milter.macros.envfrom</td>
15140266059SGregory Neil Shapiro<td><code>i, {auth_type}, {auth_authen}, {auth_ssf}, {auth_author},
15240266059SGregory Neil Shapiro{mail_mailer}, {mail_host}, {mail_addr}</code></td></tr>
15340266059SGregory Neil Shapiro<tr><td>confMILTER_MACROS_ENVRCPT</td><td>Milter.macros.envrcpt</td>
15440266059SGregory Neil Shapiro<td><code>{rcpt_mailer}, {rcpt_host}, {rcpt_addr}</code></td></tr>
15540266059SGregory Neil Shapiro</table>
15640266059SGregory Neil ShapiroFor information about available macros and their meanings, please
15740266059SGregory Neil Shapiroconsult the sendmail documentation.
15840266059SGregory Neil Shapiro<hr size="1">
15940266059SGregory Neil Shapiro<font size="-1">
1605ef517c0SGregory Neil ShapiroCopyright (c) 2000-2003 Sendmail, Inc. and its suppliers.
16140266059SGregory Neil ShapiroAll rights reserved.
16240266059SGregory Neil Shapiro<br>
16340266059SGregory Neil ShapiroBy using this file, you agree to the terms and conditions set
1645ef517c0SGregory Neil Shapiroforth in the LICENSE.
16540266059SGregory Neil Shapiro</font>
16640266059SGregory Neil Shapiro</body> </html>
167