path: root/en_US.ISO8859-1/articles/relaydelay/article.xml

<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.2-Based Extension//EN"
	"../../../share/xml/freebsd42.dtd" [
<!ENTITY % entities PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Entity Set//EN" "../../share/xml/entities.ent">
%entities;
<!ENTITY % not.published "IGNORE">
]>

<!--
    $FreeBSD$
-->

<article lang='en'>
  <articleinfo>
    <title>Using Greylist with &os;</title>

    <author>
      <firstname>Tom</firstname>
      <surname>Rhodes</surname>
      <affiliation>
        <address><email>trhodes@FreeBSD.org</email></address>
      </affiliation>
    </author>

    <copyright>
      <year>2004</year>
      <holder>The &os; Documentation Project</holder>
    </copyright>

    <pubdate>$FreeBSD$</pubdate>

    <releaseinfo>$FreeBSD$</releaseinfo>

    <abstract>
      <para>An article written for the sole purpose of explaining
        the relaydelay system on a &os; mail server.  A relaydelay
	or greylisting server cuts down on spam simply by issuing
	a <errorname>TEMPFAIL</errorname> error message to
	every incoming email.  The purpose behind this idea
	is that most spammers use their personal computers with
	software to do their spamming.  A real mail server should
	queue the message and try to send it later.  Thus the
	spammer most likely moves on to the next host in place
	of trying to send the email again.  This is an excellent
	idea; at least until the spammers begin to use software
	that offers to try again.  But how does this work exactly?
	Well, when an email is received the message
	<acronym>ID</acronym> is stored	in a database and the
	<errorname>TEMPFAIL</errorname> is returned along with the
	email.  If the email is resent, the message
	<acronym>ID</acronym> will be checked against the message
	<acronym>ID</acronym>s currently stored in the database.
	If it exists in the database then the email is permitted to reach its
	intended recipient.  Otherwise,	the <acronym>ID</acronym>
	will be stored and a <errorname>TEMPFAIL</errorname> will
	be issued.  This cycle will repeat with every email which
	comes into the server.  From my personal experience, this
	really does cut out 90% of the spam.</para>
    </abstract>
  </articleinfo>

  <sect1>
    <title>Basic Configuration</title>

    <para>We need to install the threaded <command>perl</command>.
      Install <filename role="package">lang/perl5.8</filename>
      with the <makevar>USE_THREADS=yes</makevar> variable
      set.  The current version of <command>perl</command>
      may need to be removed first; errors will be reported
      by the install process if this is necessary.</para>

    <note>
      <para>This will require all ports which require
        <command>perl</command> to be rebuilt and reinstalled;
	<filename role="package">ports-mgmt/portupgrade</filename>
	is perfect for this.  At least it will point out which
	ports have been removed and which will need to be
	reinstalled.</para>
    </note>

    <para>Now for the database server;
      <application>MySQL</application> is perfect for this
      sort of work.  Install the
      <filename role="package">databases/mysql40-server</filename>
      along with
      <filename role="package">databases/p5-DBD-mysql40</filename>.
      The previous port should imply the installation of
      <filename role="package">databases/p5-DBI-137</filename>
      so that knocks off another step.</para>

    <para>Install the <command>perl</command> based portable
      server plugin, <filename role="package">net/p5-Net-Daemon</filename>
      port.  Most of these port installations should have
      been straight forward.  The next step will be more
      involved.</para>

    <para>Now install the
      <filename role="package">mail/p5-Sendmail-Milter</filename>
      port.  As of this writing the <filename>Makefile</filename>
      contains a line beginning with <makevar>BROKEN</makevar>,
      just remove it or comment it out.  It is only marked
      this way because &os; neither has nor installs
      a threaded <command>perl</command> package by default.  Once that
      line is removed it should build and install perfectly
      fine.</para>

    <para>Create a directory to hold temporary configuration
      files:</para>

    <screen>&prompt.root; <userinput>mkdir /tmp/relaydelay</userinput>
&prompt.root; <userinput>cd /tmp/relaydelay</userinput></screen>

    <para>Now that we have a temporary directory to work in, the
      following <acronym>URL</acronym>s should be sent to the
      <command>fetch</command> command:</para>

    <screen>&prompt.root; <userinput>fetch http://projects.puremagic.com/greylisting/releases/relaydelay-0.04.tgz</userinput>
&prompt.root; <userinput>fetch http://lists.puremagic.com/pipermail/greylist-users/attachments/20030904/b8dafed9/relaydelay-0.04.bin</userinput></screen>

<!-- NOTE TO TOM RHODES:  HAVING THE SOFTWARE LINKED HERE IS A BAD IDEA IN
     CASE SOME ASSHOLE UPDATES IT.  I SHOULD PROBABLY ARCHIVE THE OTHER URL
     SCRIPTS AND OTHER SHIT AS WELL.  -->

    <para>The source code should now be unpacked:</para>

    <screen>&prompt.root; <userinput>gunzip -c relaydelay-0.04.tgz | tar xvf -</userinput></screen>

    <para>There should now be several files into the temporary directory
      by this point.  The appropriate information can now be passed to
      the database server by importing it from the
      <filename>mysql.sql</filename> file:</para>

    <screen>&prompt.root; <userinput>mysql &lt; relaydelay-0.04/mysql.sql</userinput></screen>

    <para>And patch the other files with the
      <filename>relaydelay.bin</filename> by running:</para>

    <screen>&prompt.root; <userinput>patch -d /tmp/relaydelay/relaydelay-0.04 &lt; relaydelay.bin</userinput></screen>

    <para>Edit the <filename>relaydelay.conf</filename> and the
      <filename>db_maintenance.pl</filename> file to append the
      correct username and password for the
      <application>MySQL</application> database.  If the database was
      built and installed like the above then no users or passwords
      exist.  This should be altered before putting this into
      production, that is covered in the database documentation and
      is beyond the scope of this document.</para>

    <para>Change the working directory to the
      <filename class="directory">relaydelay-0.04</filename>
      directory:</para>

    <screen>&prompt.root; <userinput>cd relaydelay-0.04</userinput></screen>

    <para>Copy or move the configuration files to their respective
      directories:</para>

    <screen>&prompt.root; <userinput>mv db_maintenance.pl relaydelay.pl /usr/local/sbin</userinput>
&prompt.root; <userinput>mv relaydelay.conf /etc/mail</userinput>
&prompt.root; <userinput>mv relaydelay.sh /usr/local/etc/rc.d/</userinput></screen>

    <para>Test the current configuration by running:</para>

    <screen>&prompt.root; <userinput>sh /usr/local/etc/rc.d/relaydelay.sh start</userinput></screen>

    <note>
      <para>This file will not exist if the previous &man.mv.1; commands
	were neglected.</para>
    </note>

    <para>If everything worked correctly a new file,
      <filename>relaydelay.log</filename>, should exist in
      <filename class="directory">/var/log</filename>.  It should
      contain something similar to the following text:</para>

    <programlisting>Loaded Config File: /etc/mail/relaydelay.conf
Using connection 'local:/var/run/relaydelay.sock' for filter relaydelay
DBI Connecting to DBI:mysql:database=relaydelay:host=localhost:port=3306
Spawned relaydelay daemon process 38277.
Starting Sendmail::Milter 0.18 engine.</programlisting>

    <para>If this does not appear then something went wrong, review
      the screen output or look for anything new in the
      <filename>messages</filename> log file.</para>

    <para>Glue everything together by adding the following line to
      <filename>/etc/mail/sendmail.mc</filename> or the customized
      site specific <filename>mc</filename> file:</para>

    <programlisting>INPUT_MAIL_FILTER(`relaydelay', `S=local:/var/run/relaydelay.sock, T=S:1m;R:2m;E:3m')dnl</programlisting>

    <para>Rebuild and reinstall the files in the
      <filename>/etc/mail</filename> directory and restart
      <command>sendmail</command>.  A quick <command>make</command>
      <maketarget>restart</maketarget> should do the trick.</para>

    <para>Obtain the <command>perl</command> script located at
      <ulink url="http://lists.puremagic.com/pipermail/greylist-users/2003-November/000327.html">
      http://lists.puremagic.com/pipermail/greylist-users/2003-November/000327.html</ulink>
      and save it in the
      <filename class="directory">relaydelay-0.04</filename>
      directory.  In the following examples this script is
      referred to as <filename>addlist.pl</filename>.</para>

    <para>Edit the <filename>whitelist_ip.txt</filename> file and
      modify it to include <acronym>IP</acronym> addresses of servers
      which should have the explicit abilities to bypass the
      <application>relaydelay</application> filters.  i.e., domains
      from which email will not be issued a
      <errorname>TEMPFAIL</errorname> when received.</para>

    <para>Some examples could include:</para>

    <programlisting>192.168.   # My internal network.
66.218.66       # Yahoo groups has unique senders.</programlisting>

    <para>The <filename>blacklist_ip.txt</filename> file should
      be treated similarly but with reversed rules.  List within
      this file <acronym>IP</acronym>s which should be denied without
      being issued a <errorname>TEMPFAIL</errorname>.  This list of
      domains will never have the opportunity to prove that they are
      legitimate email servers.</para>

    <para>These files should now be imported into the database with
      the <filename>addlist.pl</filename> script obtained a few
      lines ago:</para>

    <screen>&prompt.root; <userinput>perl addlist.pl -whitelist 9999-12-31 23:59:59 &lt; whitelist_ip.txt</userinput>
&prompt.root; <userinput>perl addlist.pl -blacklist 9999-12-31 23:59:59 &lt; blacklist_ip.txt</userinput></screen>

    <para>To have <application>relaydelay</application> start with
      every system boot, add the
      <option>relaydelay_enable="YES"</option> to the
      <filename>/etc/rc.conf</filename> file.</para>

    <para>The <filename>/var/log/relaydelay.log</filename> log file
      should slowly fill up with success stories.  Lines like the
      following should appear after a short time, depending on how
      busy the mail server is.</para>

    <programlisting>=== 2004-05-24 21:03:22 ===
Stored Sender: &lt;someasshole@flawed-example.com&gt;
Passed Recipient: &lt;local_user@pittgoth.com&gt;
  Relay: example.net [XXX.XX.XXX.XX] - If_Addr: MY_IP_ADDRESS
  RelayIP: XX.XX.XX.XX - RelayName: example.net - RelayIdent:  - PossiblyForged: 0
  From: someasshole@flawed-example.com - To: local_user
  InMailer: esmtp - OutMailer: local - QueueID: i4P13Lo6000701111
  Email is known but block has not expired.  Issuing a tempfail.  rowid: 51
  IN ABORT CALLBACK - PrivData: 0&lt;someasshole@flawed-example.com&gt;</programlisting>

    <para>The following line may now be added to
      <filename>/etc/newsyslog.conf</filename> to cause for
      <filename>relaydelay.log</filename> rotation at every
      100 <acronym>Kb</acronym>:</para>

    <screen>/var/log/relaydelay.log                 644  3     100  *     Z</screen>

    <!-- XXX What text does this note belong with? -->
    <note>
      <para>At some point there was an error about improper
        <command>perl</command> variables in the
	<filename>/etc/mail/relaydelay.conf</filename>.  If those
	two variables are commented out then configuration may
	proceed as normal.  Just remember to uncomment them before
	starting the <command>relaydelay</command> process.</para>
    </note>
  </sect1>
</article>