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

SYNOPSIS
      use Mail::SMTP::Honeypot;

      run_honeypot($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 honeypot.

    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 honeypot 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.honeypot.pl 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.
      # this is probably not what you want if you use virtual IP's
      # and have a real mail client on the same host. so...
      # specify the host 'answerback name' here.
      # [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,

      ## NOTE:      see Concurrent Daemon Operation in the
      ##            documentation for setup where another
      ##            mail daemon is running on the same host.
  
      # 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 10 seconds
      #
      #     delay           => 10,

      # syslog facility, one of:
      #     LOG_KERN LOG_USER LOG_MAIL LOG_DAEMON
      #     LOG_AUTH LOG_SYSLOG LOG_LPR LOG_NEWS
      #     LOG_UUCP LOG_CRON LOG_AUTHPRIV LOG_FTP
      #     LOG_LOCAL0 LOG_LOCAL1 LOG_LOCAL2 LOG_LOCAL3
      #     LOG_LOCAL4 LOG_LOCAL5 LOG_LOCAL6 LOG_LOCAL7
      #
      # You should not need to change this
      #
      #     log_facility    => 'LOG_MAIL',

      # 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_WARNING',

      # log verbosity
      #     0 connect only
      #     1 + To: & From:
      #     2 + bad commands
      #     3 + trace execution
      #     4 + deep trace with sub names
      # [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      => 10,

      # 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.honeypot.pl [-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
    rc.honeypot.pl if the path for perl is not in scope during boot.

      #!/bin/sh
      #
      # shell script 'rc.honeypot'
      #
      /path/to/rc.honeypot.pl $*

    A sample shell script is included in the distribution as rc.honeypot

    NOTE: suggest you test your configuration as follows...

      Set:  verbose => 3,
            delay   => 5,

      ./rc.honeypot -d start

    Connect to the daemon from a host not on the same subnet and watch the
    output from daemon to verify proper operation.

    Correct the configuration values and ENJOY!

  Standalone Operation

    For operation on a host where Mail::SMTP::Honeypot is the only SMTP
    daemon, the default configuration will work for most installations.

  Concurrent Daemon Operation

    To operate Mail::SMTP::Honeypot concurrently with another mail daemon on
    the same host you must do the following:

    1) add a virtual IP address for the daemon to answer. The IP address in
    the rc.honeypot.pl config section should be left commented out so that
    the daemon will bind to INADDR_ANY.
    In your startup sequence, execute the following: (example for Linux)

      #/bin/sh
      #
      # Edit for your setup.
      NETMASK="255.255.255.0"       # REPLACE with YOUR netmask!
      NETWORK="5.6.7.0"             # REPLACE with YOUR network address!
      BROADCAST="5.6.7.255"         # REPLACE with YOUR broadcast address
      # assign a virtual IP address
      IPADDR="5.6.7.8"

      # assign ethernet device
      DEVICE="eth0"                 # REPLACE with your external device
      LUN="0"

      # Note:       the "real" IP address has no LUN
      #             virtual IP's are assigned LUN's starting with '0'
      #
      # i.e.        host IP = 5.6.7.1       eth0
      # virtIP      5.6.7.8         LUN 0   eth0:0
      # virtIP      5.6.7.9         LUN 1   eth0:1

      IFACE=${DEVICE}:${LUN}
      /sbin/ifconfig ${IFACE} ${IPADDR} broadcast ${BROADCAST} netmask ${NETMASK}
      /sbin/route add ${IPADDR} dev ${IFACE}
      echo Configuring $IFACE as $IPADDR

    2) run the honeypot daemon on an unused port.
    Select a high port number that will not interfere with normail operation
    of the host SMTP daemon or other services on the host.

      i.e.  in the config section of rc.honeypot.pl

            port    => 10025,

    3) add packet filter rules to redirect queries.
    This example is for IPTABLES on Linux. Similar rules would apply for
    other filter packages.

      # allowed chain for TCP connections
      iptables -N allowed
      iptables -A allowed -p tcp --syn -j ACCEPT
      iptables -A allowed -p tcp -m state --state ESTABLISHED,RELATED -j ACCEPT
      iptables -A allowed -p tcp -j DROP

      # drop all external packets target on honeypot daemon
      iptables -t nat -A PREROUTING -p tcp -s 0/0 --dport 10025 -j DROP
      iptables -t nat -A PREROUTING -p tcp -d 5.6.7.8 --dport 25 -j REDIRECT --to-port 10025
      # alternate DNAT statement
      # iptables -t nat -a PREROUTING -p tcp -d 5.6.7.8 --dport 25 -j DNAT --to 5.6.7.8:10025

      ## if you are running SpamCannibal, add this rule to capture IP's of connecting hosts
      ## iptables -A INPUT -p tcp -i eth0 --dport 10025 -j QUEUE

      # allow the internal port to connect
      iptables -A INPUT -p tcp -s 0/0 --dport 10025 -j allowed

EXPORTS
    Only one function is exported by Honeypot.pm. This function is called in
    the rc.honeypot.pl.sample script to launch the honeypot daemon.

    * run_honeypot($config); # with @ARGV
        Launch the honeypot daemon.

          input:        config hash
          returns:      nothing (exits)

COPYRIGHT
    Copyright 2004 - 2014, 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>

SEE ALSO
    the Mail::SpamCannibal manpage on CPAN or spamcannibal.org

