Rattler v1.0 <http://wyrmsoft.tzo.net/rattler/>
Plugin For Back Orifice 2000
Copyright (c) 1999 by AdTropis <mataru@mail.airmail.net>

Licensed under the GNU Public License (GPL)
<http://www.gnu.org/copyleft/gpl.html>


--------------
 Introduction
--------------

    Rattler is a Back Orifice 2000 plugin that sends e-mail messages to a
specified user when the IP address of the Back Orifice host machine
changes.  This can be extremely useful for users who have Back Orifice
servers running on dial-up machines and/or machines configured for DHCP.


-------
 Files
-------

    The following files should be included in the Rattler plugin
distribution zip file (Rattler10.zip):

        Rattler.Dll      - The plugin dll
        Rattler.Txt      - This text file
        RattlerSrc.Zip   - The source code to Rattle

    The following files should be included in the Rattler source
distribution zip file (RattlerSrc.Zip):

        Rattler.cpp      - Rattler C++ source
        Rattler.h        - Rattler header file
        Rattler.def      - DLL exports
        config.cpp       - Config.cpp from BO2K SDK
        Rattler.dsw      - Visual C++ workspace file
        Rattler.dsp      - Visual C++ project file
        Rattler.Txt      - This text file

    If there are files missing, please refer to the official Rattler
homepage to download the full distribution.


--------------
 Installation
--------------

    Installation is a snap.  Simply unzip the 'Rattler10.zip' file into
any directory.  Then copy the 'Rattler.Dll' file to your Back Orifice
2000 plugin directory.  Now when you create server installation packages
you can insert the 'Rattler.Dll' plugin into the server package.

    If you want to tweak parts of Rattler (or whatever) simply unzip the
'RattlerSrc.Zip' file into a seperate directory.  A Visual C++ workspace
file is included for easy development in Visual C++ 5.0/6.0.


----------------------
 Plugin Configuration
----------------------

    When the plugin is inserted into a server installation package, there
are several parameters that need to be set to ensure proper usage of the
plugin.  Each parameter can be accessed by using the Rattler menu
Configuration parameters are list below:

    BOOL     Run On Plugin Load: Rattler will startup when the plugin is
                                 loaded

    NUMERIC  Query Delay:        Specifies the number of seconds to wait
                                 between each IP check

    STRING   Mail Host:          Specifies the SMTP (not POP!) mail host
                                 to use in order to send e-mail messages

    NUMERIC  Mail Port:          Specifies the port number of the SMTP mail
                                 host to use (probably won't need to change it)

    STRING   Mail From:          Specifies the name to use in the 'From:'
                                 field of the e-mail message

    STRING   Rcpt To:            Specifes the name to use in the 'To:' field
                                 of the e-mail message (must be a valid e-mail
                                 address!)

    STRING   Subject:            Specifies the subject of the message when
                                 an e-mail message is sent

    NUMERIC  Retries:            Specifies the number of connection retries
                                 when send an e-mail message

    NUMERIC  Retry Delay:        Specifies the number of seconds to wait
                                 between connection retries.

    BOOL     Notify On Startup:  If TRUE Rattler will send an e-mail after it
                                 has retrieved the first IP address block.  If
                                 FALSE, Rattler will only send an e-mail after
                                 an IP address change has been detected.

    BOOL     Notify Local Hosts: If TRUE Rattler will send an e-mail message
                                 for local network IP address changes (* see
                                 below for more on local networks addresses)

    BOOL     Use Debugging:      If TRUE Rattler will send messages to a
                                 debugging file (specified by 'Debugging File')

    STRING   Debugging file:     Specifies the location of the debugging file
                                 to use (* see below on debugging)


--------------------------------------
 Server-Side Configuration  & Options
--------------------------------------

    Rattler also allows for 'dynamic' configuration once it is loaded into
the Back Orifice server.  Once the Back Orifice server is started, just log
into it with the client program and then you can change all of the Rattler
options through the Rattler menu.  Here is a list of the menu options:

    Status           Shows the status of the Rattler plugin as well as the
                     number of attempted messages and messages sent and the
                     current state of the IP table.  It also allows a user
                     to manually send an e-mail message immediately.

    Configuration    Shows the current configuration set for the Rattler
                     plugin.  Also allows the user to load the default
                     configuration is desired.

    Config: Status   Allows the user to shutdown or startup the Rattler
                     service.  Also allows for toggling the 'Run On Load'
                     option.

    Config: Host     Allows for configuration of the SMTP mail host to
                     send mail to.  The port and server name can be changed.

    Config: Users    Allows for changing the names in the 'MAIL FROM' and
                     'RCPT TO' options

    Config: Subject  Allows configuration of the subject to be sent in each
                     e-mail that is sent by Rattler.

    Config: Options  Allows the user to change the current connect retry
                     count, the 'Notify Startup' option, and the 'Notify
                     Local' option.

    Config: Delays   Allows for changing the 'Query Delay' and 'Retry Delay'
                     options.

    Config: Debug    Allows for enabling/disabling debugging and changing
                     the location of the debugging file.

    All changes take effect immediately.  However, when changing the 'Notify
Local' option, a mail message will NOT be sent unless a local IP is changed or
the user does so manually.

    All options are also stored in the registry so that any configuration
changes will be in effect the next time that the plugin is started.  All
options are stored under HKEY_LOCAL_MACHINE\SOFTWARE\WyrmSoft\Rattler.


------------------------
 Client Side Operations
------------------------

    Rattler is a server-side-only plugin.  There are no client options that can
be set.


--------------
 How It Works
--------------

    Basically the operation of Rattler is very simple.  It simply obtains
a block of IP addresses that correspond to the machine on which it is
running.  If there have been any additions to this IP table Rattler sends
an e-mail message containing the current IP table to a pre-defined recipient.

    By default Rattler does not send e-mail regarding changes to local
network addresses.  But just what is a local network address?  Well, the
first (and, hopefully, most obvious) is, of course, localhost (127.0.0.1).
However, there are three other sets of network addresses that I call local:

    10.0.0.0                      MASK 255.0.0.0       Class A
    172.16.0.0 - 172.31.0.0       MASK 255.255.0.0     Class B
    192.168.0.0 - 192.168.255.0   MASK 255.255.255.0   Class C

    These three network addresses are supposed to be used on LANs that do not
have a direct connection to the internet.  Therefor, I consider them local.

    Of course, by setting the 'Notify Local' option to TRUE, changes to local
network addresses will make Rattler send an e-mail message (this might be
good for machines that are configured for DHCP).


-----------
 Debugging
-----------

    You probably won't have to use the debugging  option until you run into
problems.  Be prepared, though.  The debugging option will generate alot of
messages, especially if the query delay is set to a low value.

    If you use the debugging option and notice that there is a fault in the
Rattler plugin, please let me know and I'll fix it as fast as I can.


-------------
 Development
-------------

    The source code provided in the Rattler distribution is free for you
to modify according to the terms of the GNU Public License.  Feel free
to make any changes you see fit.  If you do make changes, please send them
to me.  I would very much like to hear your comments on my work.

    The 'Rattler.Dll' file was compiled using Visual C++ 5.0.


------------
 Conclusion
------------

    Thanks go out to The Cult of the Dead Cow for making Back Orifice as well
as Brian Enigma for his work on Butt Trumpet 2000 (from which I got a few
snippets of code).

    Questions or comments?  Please send me an e-mail: mataru@mail.airmail.net

    Enjoy!

                                                               - AdTropis -