contrib/sendmail-8.14/libmilter/docs/installation.html

   1 <HTML>
   2 <HEAD><TITLE>Installation and Configuration</TITLE>
   3 </HEAD>
   4 <BODY>
   5 <!--
   6 $Id: installation.html,v 1.23 2006/08/31 17:16:03 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
  17 To 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>
  28 Your compile command line will look like
  29 <PRE>
  30 cc -I/path/to/include -I/path/to/sendmail -c myfile.c
  31 </PRE>
  32 and your linking command line will look something like
  33 <PRE>
  34 cc -o myfilter [object-files] -L[library-location] -lmilter -pthread
  35 </PRE>
  36
  37 <H2><A name="config">Configuring Sendmail</A></H2>
  38
  39 If you use a sendmail version older than 8.13 please see
  40 the instructions for your version.
  41 The default compilation options for sendmail enable support
  42 for milters since 8.13.
  43
  44 <P>
  45 Next, you must add the desired filters to your sendmail configuration
  46 (.mc) file.
  47 Mail filters have three equates:
  48 The required <CODE>S=</CODE> equate specifies the socket where
  49 sendmail should look for the filter; the optional <CODE>F=</CODE> and
  50 <CODE>T=</CODE> equates specify flags and timeouts, respectively.
  51 All equates names, equate field names, and flag values are case sensitive.
  52
  53 <P>
  54 The 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
  68 If a filter is unavailable or unresponsive and no flags have been
  69 specified, the MTA will continue normal handling of the current
  70 connection.
  71 The MTA will try to contact the filter again on each new connection.
  72
  73 <P>
  74 There are three fields inside of the <CODE>T=</CODE> equate: S, R, and E.
  75 Note the separator between each is a ";" (semicolon), as ","
  76 (comma) already separates equates.
  77 The value of each field is a decimal number followed by a single letter
  78 designating the units ("s" for seconds, "m" for minutes).
  79 The 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>
 104 The following sendmail.mc example specifies three filters.
 105 The first two rendezvous on Unix-domain sockets in the /var/run directory;
 106 the 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 &gt; myconfig.cf
 115 </PRE>
 116 By default, the filters would be run in the order declared,
 117 i.e. "filter1, filter2, filter3"; however, since
 118 <CODE>confINPUT_MAIL_FILTERS</CODE> is defined, the filters will be
 119 run "filter2, filter1, filter3".
 120 Also note that a filter can be defined
 121 without adding it to the input filter list by using
 122 MAIL_FILTER() instead of INPUT_MAIL_FILTER().
 123
 124 <P>
 125 The above macros will result in the following lines being added to
 126 your .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>
 135 Finally, the sendmail macros accessible via
 136 <A HREF="smfi_getsymval.html">smfi_getsymval</A> can be configured by
 137 defining 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>
 154 For information about available macros and their meanings, please
 155 consult the sendmail documentation.
 156 <HR size="1">
 157 <FONT size="-1">
 158 Copyright (c) 2000-2003, 2006 Sendmail, Inc. and its suppliers.
 159 All rights reserved.
 160 <BR>
 161 By using this file, you agree to the terms and conditions set
 162 forth in the LICENSE.
 163 </FONT>
 164 </BODY>
 165 </HTML>