NAME
    Mail::SMTP::Honeypot -- Dummy mail server

SYNOPSIS
      use Mail::SMTP::Honeypot;

      run($config)

DESCRIPTION
    Mail::SMTP::Honeypot is a perl module that appears to provide all the
    functionality of a standard SMTP server except that when the targeted
    command state is detected (default DATA), it terminates the connection
    with a temporary failure and the response:

        421 Service not available, closing transmission channel

    The purpose of this module is to provide a spam sink on a tertiary MX
    host. The module daemon is run on an MX host with a very high priority
    number specified in it's DNS record. i.e.

      some_mail_domain.com  IN MX 9999 lastmx.servicedomain.com.

    Since many spammers target this mail server in the hope that its
    configuration and/or security is not as strong or well maintained as the
    primary mail host for a domain. In the off chance that a real message is
    sent to the server, the TEMPORARY failure code will simply make the
    sending host retry later -- probably with the lower priority numbered
    host. Meanwhile, the server target by the spam source has its resources
    consumed by spamdeny.

    Honeypot does not spawn children and holds only a small reference to
    each thread that it holds to a client, thus consuming minimal resources.
    It can produce logs useful in analyzing the spam traffic to your site.
    Using it with a detach in CONN mode is adequate for triggering a
    companion spam program such as Mail::SpamCannibal while consuming
    minimum host resources. At our site, we simply run spamdeny on the same
    host as our secondary MX but on a different IP address.

    Honeypot provides various levels of connection and transaction logging
    that can be set in the configuration.

    A delay may be inserted between the receipt of each command and the
    response from the server daemon to slow down the sending client.

CONFIGURATION
    Edit the rc.spamdeny file to change or set the following:

      my $config = {

      # specify the directory for the pid file for this daemon
      # [required]
      #
            piddir          => '/var/run',

      # deny at command state, one of:
      #     CONN EHLO HELO MAIL RCPT DATA
      # defaults to DATA if not specified
      # [optional]
      #     deny            => 'DATA',

      # specify the local domain name, defaults to local hostname
      # [optional]
      #
      #     hostname        => 'my.host.name.com',

      # specify the IP address to bind the listening port
      # defaults to ALL interfaces (INADDR_ANY)
      # [optional]
      #
      #     ip_address      => '1.2.3.4',

      # listen port -- default 25
      # this is useful for debugging purposes
      # [optional]
      #
      #     port            => 25,

      # specify the response delay after connect or upon
      # receipt of an smtp command from the client
      #
      # NOTE:       if a response is not received
      #             from the client in this time
      #             period, the smptdeny daemon will
      #             issue a 421 response and disconnect
      # [optional] default 45 seconds
      #
      #     delay           => 45,

      # syslog log level or (none), one of:
      #     STDERR LOG_EMERG LOG_ALERT LOG_CRIT LOG_ERR
      #     LOG_WARNING LOG_NOTICE LOG_INFO LOG_DEBUG
      #
      # NOTE:       the command line -d flag overrides
      #             this and sets the level to STDERR
      # [optional]
      #
            syslog          => 'LOG_INFO',

      # log verbosity
      #     0 connect only
      #     1 + To: & From:
      #     2 + bad commands
      #     3 + trace execution
      # [optional]
      #
            verbose         => 0,

      # DNS host, if you do not have a resolver
      # on your host or for debugging
      # default: as returned by your resolver for local dns
      # [optional]
      #     dnshost         => 'use.default',

      # DNS port, useful for debugging
      # [optional] default 53
      #
      #     dnsport         => 53,

      # timeout for DNS PTR queries
      # [optional] default: use 'delay' above
      #
      #     DNStimeout      => 45,

      # maximum number of connected clients
      # [optional] default 100
      #
      #     maxthreads      => 100,

      # maximum number of commands per client
      # [optional] default 100
      #
      #     maxcmds         => 100,

      # disconnect the remote after this much time
      # [optional] default 300 seconds
      #
      #     disconnect      => 300,

      };

OPERATION
    Launch the daemon with the command:

            rc.spamdeny [-d] [start | stop | restart]

    The '-d' flag, this overides the config settings and reports logging to
    STDERR

    On some systems it may be necessary to wrap a shell script around spam
    deny if the path for perl is not in scope during boot.

      #!/bin/sh
      /usr/bin/perl $*

    * run_honeypot($config); # with @ARGV
        The only EXPORTED function, launches the smtpdeny daemon.

          input:        config hash     # see rc.spamdeny
          returns:      nothing (exits)

EXPORT
            run_honeypot

COPYRIGHT
    Copyright 2004 - 2006, Michael Robinton <michael@bizsystems.com>

    This program is free software; you can redistribute it and/or modify it
    under the terms of the GNU General Public License (except as noted
    otherwise in individuals sub modules) published by the Free Software
    Foundation; either version 2 of the License, or (at your option) any
    later version.

    This program is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
    Public License for more details.

    You should have received a copy of the GNU General Public License along
    with this program; if not, write to the Free Software Foundation, Inc.,
    59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

AUTHOR
    Michael Robinton <michael@bizsystems.com>