Rattler v1.10
Plugin For Back Orifice 2000 v1.0
Copyright (c) 1999 by AdTropis
Licensed under the GNU Public License (GPL)
-----------------
Version History
-----------------
v1.10: Released 10/03/99
> Changed debugging messages a bit, added more debugging messages
> WinSock is now initialized when the plugin is loaded
> Fixed bug in GetIpList()
> Fixed possible bug when calling gethostname() in SendMailMessage()
> Added "Use Registry" option
> Added multiple recipient capability
> Added formatted subject line
> Switched TCP/IP socket operations to non-blocking
> Changed name of DLL to srv_rattler.dll for consistency
1.01: Released 08/29/99
> Fixed bug in WinSock init code
> Fixed bug in getting mail host name
> Fixed bug in getting TCP protocol information
> Fixed bug in debugging options change
1.0: Released 08/23/99
> Initial release
------------
What's New
------------
New features:
x) Added option to allow for toggling registry-based configuration.
Now you can select whether Rattler looks to the registry for
configuration information or not.
x) Added multiple recipient capability so that the mail message may
be sent to more than one e-mail address.
x) Added formatted subject line functionality. By using variables
like '%u' and '%h' in the subject line, you can have the e-mail
subject remain consistent across many servers.
Minor bugfixes:
x) The WinSock was only being initialized when actually transmitting
a mail message. This could (and probably should) have been causing
problems with getting the local IP address list as gethostname()
and gethostbyname() both require the WinSock to be initialized
before a call is made to these functions. Now the WinSock is
initialized when the plugin is loaded, ensuring that it will
be initialized when calls to network functions are made.
x) If GetNumAddr() returned 0 to GetIpList(), it would fail giving an
error. However, if this is run on a stand-alone machine that only
dials up to the internet, it is possible that there would not be
any addresses in the list, and therefore, a return of 0 is valid.
x) I received a report about the gethostname() and GetUserName()
messages returning corrupted data when called on systems that
use AOL. Now, if either of these fail, the string "unknown" is
used to fill the buffer.
x) The mail sending mechanism now uses a non-blocking socket. The
reason for this fix is so that multiple server messages can be
read without locking up the machine sending the mail message. This
should fix problems where the SMTP server was sending back multiple
"250" reply messages after sending the "HELO".
--------------
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.
--------------
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. Therefore, 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).
-------
Files
-------
The following files should be included in the Rattler plugin
distribution zip file (rattler110.zip):
srv_rattler.dll - The plugin dll
rattler.txt - This text file
rattlersrc.zip - The source code to Rattler
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
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 'rattler110.zip' file into
any directory. Then copy the 'srv_rattler.dll' file to your Back Orifice
2000 plugin directory. Now when you create server installation packages
you can insert the 'srv_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 Use Registry: If this is set to TRUE, Rattler will
store all of it's configuration changes
in the registry for later retrieval.
This allows for changes to remain
persistent, even when the BO2K server is
restarted. If this is set to FALSE, the
registry is not used at all.
* Note: Also see the section below on
registry usage
BOOL Run On Plugin Load: Rattler will start checking IP addresses
when the plugin gets 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 (you probably won't need to
change this).
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. This can be a single
e-mail address, or a list of addresses
delimited by a ';' or a ','.
STRING Subject: Specifies the subject of the message when
an e-mail message is sent. (* see section
below on subject variables)
NUMERIC Retries: Specifies the number of times to retry
connecting to the SMTP server.
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.
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.
----------------
Registry Usage
----------------
When installing the Rattler plugin on a system, there is an important
consideration to be made: whether or not to use the registry to store
configuration data. Both options are explored below.
Persistent configuration ("Use Registry" = TRUE):
You will want to use this configuration if you think that you will
want to make changes to Rattler's configuration in a permanent fashion.
Any changes made to Rattler's configuration will be stored in the target
machines registry under HKEY_LOCAL_MACHINE\Software\WyrmSoft\Rattler.
The main problem with this mode of operation is that when trying to
re-install the BO2K server with new options, the settings that are stored
in the registry will still take effect. However, by using the "Load Default
Config" option under the "Rattler-> Configuration" menu in the BO2K
GUI client, you can load the settings stored in the 'srv_rattler.dll' file
and overwrite the options stored in the registry.
Temporary configuration ("Use Registry" = FALSE):
You will want to use this configuration if you don't want to save
configuration changes. If this configuration is used, the registry
is not used at all (queries or writes). The only problem with this
mode of operation is that any changes made to Rattler's configuration
will be lost the next time the BO2K server is restarted.
------------------------
Subject Line Variables
------------------------
Rattler now supports formatting the subject line through the use of
various variables. This allows a BO2K server adminstrator to maintain
consistency among many servers with ease. The following variables are
currently accepted:
%h - Inserts the current host name
%u - Inserts the current user name
%v - Inserts the current Rattler version
%% - Inserts a '%'
Example:
JoeUser is logged into JoeComputer using Rattler v1.10. If the subject
is configured as:
"Rattler Information (v%v): %u@%h"
the server adminstrator will receive e-mails with the subject as:
"Rattler Information (v1.10): JoeUser@JoeComputer"
------------------------
Client Side Operations
------------------------
Rattler is a server-side-only plugin.
-----------
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 'srv_rattler.dll' file was compiled using Visual C++ 6.0 SP3.
--------------
Future Plans
--------------
I already have plans to upgrade Rattler to the new BO2K 1.1 plugin
interface when it is released. When this does occur, this will be released
as version 1.11. At this time I see version 1.1X being the last release
version for Rattler. I just can't see what else you could want out of
this kind of plugin.
------------
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).
Thanks also go out to all of the people who sent in feature requests and
bug reports. Extra special thanks go out to those who worked with me to get
the peskier bugs fixed.
Questions or comments? Please send me an e-mail: mataru@mail.airmail.net
Enjoy!
- AdTropis -