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

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