"Fossies" - the Fresh Open Source Software Archive

Member "Mail-SPF-Query-1.999.1/examples/sendmail-milter-INSTALL.txt" (31 Dec 2005, 11834 Bytes) of package /linux/privat/old/Mail-SPF-Query-1.999.1.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1        by Mark, System Administrator Asarian-host.org
    2 
    3 1. INTRODUCTION
    4 ---------------
    5 
    6 spf-milter is a Milter, which works with Sendmail 8.12 and up, and provides
    7 an SPF-compliant extension to the SMTP communication between your MTA and
    8 connecting clients. See http://www.openspf.org for details about SPF itself.
    9 
   10 spf-milter is written entirely in Perl, and uses the native threaded Milter
   11 model. spf-milter is licensed under GPL.
   12 
   13 
   14 2. PREREQUISITES
   15 ----------------
   16 
   17 spf-milter requires:
   18 
   19 1): Perl 5.8.x, or higher.
   20 
   21 2): Perl modules:
   22 
   23     Sendmail::Milter (version 0.18)
   24     Mail::SPF::Query (at least version 1.99!)
   25     Mail::SRS (version 0.30)
   26 
   27 
   28 3. INSTALLATION
   29 ---------------
   30 
   31 Since spf-milter is written in Perl, you need, for starters,
   32 Sendmail::Milter (at CPAN). The Milter API is threaded, so you need a
   33 thread-enabled Perl (compiled with -Duseithreads) as well. If you do not
   34 know whether you Perl supports threads, try and install Sendmail::Milter
   35 first. It will itself test the ithread functionality of your Perl for
   36 compatibility with Sendmail::Milter.
   37 
   38 I built and tested spf-milter under Perl, v5.8.0 built for
   39 i386-freebsd-thread-multi. Earlier versions of Perl versions may or may
   40 not be suitable.
   41 
   42 
   43 A) Sendmail
   44 
   45 You must be using Sendmail 8.12.x
   46 ---------------------------------
   47 
   48 Obtain the latest Sendmail 8.12.x source release from
   49 http://www.sendmail.org. Unpack it. Add the following lines to
   50 devtools/Site/site.config.m4:
   51 
   52   APPENDDEF(`conf_libmilter_ENVDEF', `-DMILTER')
   53   APPENDDEF(`conf_sendmail_ENVDEF', `-DMILTER')
   54 
   55 This enables the Milter functionality. Now build Sendmail as usual
   56 ("sh Build" in the sendmail/ directory).
   57 
   58 Add the following lines to your Sendmail "m4" configuration file
   59 (*.mc, in the cf/cf/ directory):
   60 
   61   define(`confMILTER_LOG_LEVEL',`9')dnl
   62   define(`confMILTER_MACROS_HELO', confMILTER_MACROS_HELO`, {verify}')dnl
   63   INPUT_MAIL_FILTER(`spf-milter', `S=local:/var/spf-milter/spf-milter.sock, F=T, T=C:4m;S:4m;R:8m;E:10m')
   64 
   65 Adjust the MILTER_LOG_LEVEL and T timings to your liking. Now build
   66 sendmail.cf as usual ("./Build sendmail.cf" in the cf/cf/ directory). Your
   67 newly generated sendmail.cf will now contain a section that looks like this:
   68 
   69 # Milter options
   70 O Milter.LogLevel=9
   71 O Milter.macros.connect=j, _, {daemon_name}, {if_name}, {if_addr}
   72 O Milter.macros.helo={tls_version}, {cipher}, {cipher_bits}, {cert_subject}, {cert_issuer}, {verify}
   73 O Milter.macros.envfrom=i, {auth_type}, {auth_authen}, {auth_ssf}, {auth_author}, {mail_mailer}, {mail_host}, {mail_addr}
   74 O Milter.macros.envrcpt={rcpt_mailer}, {rcpt_host}, {rcpt_addr}
   75 
   76 And this:
   77 
   78 ######################################################################
   79 ######################################################################
   80 #####
   81 #####                   MAILER DEFINITIONS
   82 #####
   83 ######################################################################
   84 ######################################################################
   85 
   86 Xspf-milter, S=local:/var/spf-milter/spf-milter.sock, F=T, T=C:4m;S:4m;R:8m;E:10m
   87 
   88 Inspect your new sendmail.cf, to see whether it does indeed contain these things.
   89 
   90 
   91 B) Startup
   92 
   93 You are already ready to start spf-milter! :)
   94 
   95 Sendmail does not need to "find" the spf-milter script. You can run it from
   96 pretty much every location. The only thing sendmail needs to do, is to be
   97 able to find the local domain socket to connect to (spf-milter creates
   98 "/var/spf-milter/spf-milter.sock" per default). If you successfully followed
   99 the above steps, then your new sendmail.cf will contain the proper local
  100 socket name.
  101 
  102 Backup your old sendmail.cf. Now, stop sendmail, and copy the new
  103 sendmail.cf to its proper location.
  104 
  105 Now, start spf-milter first! Depending on where your thread-enabled Perl
  106 resides, of course, you can, in its simplest form, start spf-milter like
  107 this:
  108 
  109 /usr/local/perl-threaded/bin/perl /usr/local/spf/sendmail-milter.pl milter
  110 
  111 We start spf-milter with at least one parameter, the user to run as.
  112 spf-milter expects to create/read/write its log, pid, and socket, all in
  113 /var/spf-milter/, and will itself create the directory, if need be, and set
  114 all appropriate permissions/ownerships.
  115 
  116 You cannot run spf-milter as root.
  117 
  118 If everything went okay, try 'ps ax', and your spf-milter will show up as:
  119 
  120 "spf-milter (perl)"
  121 
  122 Restart sendmail. Now you're done. :)
  123 
  124 
  125 C) Testing spf-milter functionality
  126 
  127 Perform two basic tests:
  128 
  129 1) Make sure legitimate mail gets through!
  130 
  131 2) Confirm that forged mail is rejected; forging mail from
  132    mengwong@vw.mailzone.com will do the trick (address used
  133    with permission).
  134 
  135 If properly rejected, you will get a 550 response, and a text with a
  136 reference to "http://www.openspf.org/why.html? ..." in the line.
  137 
  138 N.B. The actual return-text may vary from MTA to MTA, but the 550 response
  139 code SHOULD always be the same (an extended SMTP code, '550', '5.7.1').
  140 
  141 
  142 4. SRS AND FAKE DSN DETECTION
  143 -----------------------------
  144 
  145 
  146 A) Outline
  147 
  148 As of version 1.40, spf-milter comes with a new functionality: fake DSN
  149 detection. It is activated by the -S option; and, when enabled, will spot
  150 and REJECT unsigned DSN recipients. Signatures are based on SRS (Mail::SRS).
  151 This is an advanced option; it requires an MTA counterpart installation to
  152 sign outgoing envelope-from addresses, and should not be used unless you are
  153 well familiar with the entire scheme and its possible ramifications.
  154 
  155 The idea, in a nutshell, is as follows. Have an MTA sign all outgoing
  156 envelope-from addresses. Then, when we receive a DSN (bounce message with a
  157 MAIL FROM: <>), we will REJECT this DSN, unless the recipient was SRS
  158 signed. Based on the old "what goes around, comes around" adage (or rather,
  159 "what does not go around, should not come around"): if we do not ever send
  160 out unsigned envelope-from addresses, then we know we are dealing with a
  161 forgery when we receive an unsigned DSN recipient!
  162 
  163 Only use this when you have implemented an SRS signing scheme in your MTA,
  164 which will sign ALL outgoing envelope-from addresses. Unfortunately,
  165 spf-milter cannot do that for you, as the Milter specs do not allow for a
  166 method to change the envelope-from address. You may want to have a peek at
  167 my SRS + sendmail integration project, at:
  168 
  169     http://asarian-host.net/srs/sendmailsrs.htm
  170 
  171 
  172 B) How to use FAKE DSN DETECTION without SRS reversal in sendmail
  173 
  174 If your incoming mail server differs from your outgoing one, then there is
  175 way to use FAKE DSN DETECTION without setting up SRS reversal in the
  176 sendmail configuration for you incoming mail server.
  177 
  178 Since spf-milter handles your locally targeted SRS recipients, you would
  179 think that suffices. And it does. However, the Milter specification does not
  180 permit the changing of recipients at envrcpt_callback, and forces you to
  181 wait until eom_callback; thereby leaving an intermediate window, between
  182 callbacks, where sendmail itself will verify the recipients (upon return of
  183 envrcpt_callback), and conclude that your nice SRS0 bounce address does not
  184 exist on the system. The result? Sendmail will REJECT the recipient with a
  185 "User unknown" after all.
  186 
  187 The way to solve this, is to make use of sendmail's "plussed" user facility.
  188 Define two users (virtusertable), like so:
  189 
  190     SRS0+*@yourdomain.com    user
  191     SRS1+*@yourdomain.com    user
  192 
  193 (where "user" is the name of an existing user).
  194 
  195 This will provide the necessary "fallback" for the undefined in-between
  196 callback state. Mind you, these are 'dummy' addresses; they are never
  197 actually used for delivery; they are just there to prevent sendmail from
  198 bulking over your SRS addresses, in-between callbacks.
  199 
  200 Now that sendmail has these fallback wildcard addresses, spf-milter can
  201 proceed until eom_callback, where it will replace the SRS signed envelope
  202 recipient(s) with their reversed counterparts.
  203 
  204 For this to work, your SRS 'separator' character must be "+". Like so:
  205 
  206     my $srs = new Mail::SRS (Secret => 'yaddayadda', Separator => '+');
  207 
  208 So that SRS0+, SRS1+ addresses are formed.
  209 
  210 
  211 C) Start-up considerations
  212 
  213 To use SRS on spf-milter, start it with the -S parameter; a minimum command
  214 line usage would be:
  215 
  216     ./sendmail-milter-spf-1.40.pl -S milter
  217 
  218 This will place spf-milter in FAKE DSN DETECTION mode, running as user
  219 "milter".
  220 
  221 There has been some discussion on whether people should become SRS1
  222 forwarding hosts. To accomodate both parties, spf-milter can be started with
  223 an additional option, "-r". If set, spf-milter will relay non-locally
  224 resolving SRS0 addresses (reversed from SRS1 addresses). Per default,
  225 spf-milter only accepts locally resolving SRS0 addresses. If you want full
  226 SRS1 functionality, start spf-milter like so (minimal):
  227 
  228     ./sendmail-milter-spf-1.40.pl -S -r milter
  229 
  230 Whether you start spf-milter with -S or not, when relaying, spf-milter is
  231 always SRS aware (that is, when your own mailer is sending TO foreign SRS0,
  232 SRS1 addresses). The "-r" option, outside -S, only has meaning when
  233 relaying.
  234 
  235 
  236 5. COMMON QUESTIONS ANSWERED
  237 ----------------------------
  238 
  239 1) Why does spf-milter use the native threaded Milter model?
  240 
  241 Because Sendmail::Milter does.
  242 
  243 2) How does spf-milter stay stable using ithreads?
  244 
  245 Instead of using a multiplexor to split threads over individual child
  246 processes (like MIMEDefang), spf-milter 'locks' (thread-locks) its
  247 callbacks, thus effectively serializing the threads; so you get much of
  248 the effect of what the MIMEDefang multiplexor does (kinda). And since the
  249 'locked' attribute really prevents the threads from clobbering over one
  250 another, you can even use thread-unsafe package calls within those subs,
  251 like to DBI.
  252 
  253 3) By serializing all callbacks, do you not reduce performance?
  254 
  255 Without locking the subroutines, Sendmail::Milter is simply way too
  256 unstable, and effectively unusable. However, since there are 10 callbacks in
  257 total, each thread is only serialized for those occassions when two threads
  258 try and access the same sub at the same time. Otherwise they run parallel
  259 too: one thread may acces the eom_callback whilst another enters the
  260 helo_callback, for instance. In fact, as long as all threads are just
  261 slightly out of phase with one another (one callback difference minimum),
  262 they all run nicely parallel.
  263 
  264 4) Does spf-milter act prior to the DATA phase?
  265 
  266 Yes, spf-milter makes its SPF checks before the DATA phase; at
  267 envfrom_callback (at: "MAIL FROM: <address>"), or at envrcpt_callback (at:
  268 "RCPT TO: <recipient>"), when running in "mx" mode.
  269 
  270 5) Can spf-milter be used within the same sendmail configuration as
  271 MIMEDefang (and other Milters)?
  272 
  273 Yes. Quoting a bit from the libmilter documentation:
  274 
  275 +----------------------------------------+
  276 | SPECIFYING FILTERS IN SENDMAIL CONFIGS |
  277 +----------------------------------------+
  278 
  279 Filters are specified with a key letter ``X'' (for ``eXternal'').
  280 
  281 For example:
  282 
  283     Xfilter1, S=local:/var/run/f1.sock, F=R
  284     Xfilter2, S=inet6:999@localhost, F=T, T=C:10m;S:1s;R:1s;E:5m
  285     Xfilter3, S=inet:3333@localhost
  286 
  287 specifies three filters. Filters can be specified in your .mc file using
  288 the following:
  289 
  290     INPUT_MAIL_FILTER(`filter1', `S=local:/var/run/f1.sock, F=R')
  291     INPUT_MAIL_FILTER(`filter2', `S=inet6:999@localhost, F=T')
  292     INPUT_MAIL_FILTER(`filter3', `S=inet:3333@localhost')
  293 
  294 Which filters are invoked and their sequencing is handled by the
  295 InputMailFilters option:
  296 
  297     O InputMailFilters=filter1, filter2, filter3
  298 
  299 This is is set automatically according to the order of the
  300 INPUT_MAIL_FILTER commands in your .mc file. Alternatively, you can
  301 reset its value by setting confINPUT_MAIL_FILTERS in your .mc file.
  302 This options causes the three filters to be called in the same order
  303 they were specified.
  304 
  305 - Mark
  306 
  307         System Administrator Asarian-host.org
  308 
  309 -------
  310 To unsubscribe, change your address, or temporarily deactivate your subscription, 
  311 please go to http://v2.listbox.com/member/?listname=srs-discuss@v2.listbox.com