Files

• /
• gwho.pl
• portal.pl
• realm.pl
• registration.pl
• ./admin
• chatadmin.pl
• realmadmin.pl
• textadmin.pl
• useradmin.pl
• ./config
• config-ignore.pl
• config-puppet.pl
• config-puppeteer.pl
• config-realm.pl
• ./post
• dice.pl
• private.pl
• who.pl
• ./commandline
• docs/
• accepted.txt
• bio.txt
• footer.txt
• invitation.txt
• realminfo.txt
• sidebar.txt
• aup.txt
• connect.txt
• header.txt
• javascript.txt
• register.txt
• dbsetup.plx
• webchatcmd.plx
• ./Webchat
• Comm.pm
• Database.pm
• Dbm.pm
• Login.pm
• Param.pm
• Post.pm
• Table.pm
• Who.pm

./

Contains all of the files and directory in the order that they would normally appear on the web server, except for web chat and server and dbsetup.plx which would normally be placed apart.

• gwho.pl
• Also known as Global Who is On, allows to see people in all public realms
• portal.pl
• The analogy of a portal was used in the naming of this script, as it allows to access realms and all configuration controls.
• realm.pl
• Handling of chat styles and posting. This is where all of the role-playing and chatting will take place.
• registration.pl
• The registration of puppeteers script. Will send out an e-mail to confirm validity of users.

Admin

This contains all of the administrative scripts. All of which are web-based and require administrative flags to be set on the puppeteer. Note that all of the following scripts have hard coded look and feel as the author felt that administrative scripts did not need to reply on the look and feel of the system itself.

• chatadmin.pl
• This script will give you direct access to the dbms that the scripts rely on heavily for attributes. Makes sure you look through this script first as to determine all tags to be correct and/or suitable for your system
• realmadmin.pl
• Handles the basic creation of public realms and the removal of any realm.
• textadmin.pl
• Text administration, allows you to select documents stored on the database and to change them as needed. Uses a text area to achieve this. May be prudent to use a text editor as to copy and paste the changes.
• useradmin.pl
• Puppeteer control. Allows you to add/remove users, to add supervisory and administrative flags and to make a few changes as needed.

Config

These are configuration scripts that are dependent of the look and feel of the server. Except for realm-config.plx all scripts are accessible by all puppeteers as to make changes.

• config-ingore.pl
• Allows the user to add remove puppets from their ignore list. 
• config-puppet.pl
• Allows a puppeteers to add/remove puppets as well as modify tagline, titles, bios and images. An image will be downloaded from the site listed and the size will be added automatically.
• config-puppeteer.pl
• Place where a puppeteer can change their password and e-mail address. This can only be done when the password is provided.
• config-realm.pl
• Required the supervisory flag to be accessed successfully. Will allow modifications of realm rules and controls.

Post

These scripts are normally only accessed though the use of the realm.plx script.

• dice.pl
• A very simplistic dice roller that uses Math::TrulyRandom to make the 'rolls' a bit more interesting. This like private messages will make a post to the main chat window.
• private.pl
• This will simply allow you to send out private messages to those in the current realm. This will message the puppeteer and not the puppets themselves.
• who.pl
• Displays who is currently playing in the realm.

commandline

There are only two scripts in this folder. This is primarily because it's functions differ from all the others. As in they require the use of the command line, and will be seldomly access directly.

• docs/
• Default documentation, ranging from HTML headers and footers to javascript used. You can either change this before running dbsetup.plx or use textadmin.plx to handle this later.
• dbsetup.pl
• This script is encouraged with the very simple task of configuring the MySQL database will all of the needed information and tables. It will create a default user, which incidentally is the one used to connect initially to MySQL. This script requires modifications as to work. Look for the blank variable assignments near the top of the scripts.
• webchatcmd.pl
• Command line tools for the webchat system. Will handle expiration of puppeteers, realms, posts, as well as allow you to generate mailing lists by displaying the (distinct) E-Mail addresses of all the members.

Webchat

This chat server aims to be somewhat object oriented. The following folder contains classes and their methods used throughout the chat system.

• Comm.pm
• Handles all of the posting and post inserting into the database.
• Crypto.pm
• Handles encoding and cryptographic features within Ethereal.
• Database.pm
• Designed primarily to hide most of the work used to access the database. Will handle things from making a database handle to retrieving documents.
• Dbm.pm
• This class is used exclusively for accessing the DBM's used throughout the scripts for attributes. It also includes the initialization code needed to create the DBM's.
• Login.pm
• Simple authentication module, as to make the scripts easier to deal with.
• Param.pm
• Converts the parameters received into a hash, and will embed key data as either hidden fields (POST) or inline for use in GET.
• Post.pm
• Handles the display of posts
• Table
• Default table creation, used extensively in the scripts. Really cuts down on code and increases maintainability.
• Who.pm
• Primary component of who.plx, handles the retrieval and display; of who is currently on.

Installation

Before you even begin you will need to retrieve three perl modules that were not included with Ethereal realms.    This is primarily for the fact that they were not created by the author of the scripts and thus where not included. All of these modules can be retrieved by using CPAN.

• Math::TrulyRandom
• Used specifically for the seed generation in the rolls of dice
• Image::Grab
• Used to retrieve images from a listed URL. Please note requires and extensive amount of modules on it's own
• Image::Size
• Used to determine the size of retrieved image
• Crypt::MD5
• MD5 cryptographic hashing
• MIME::Base64
• Base64 encoding and decoding capabilities

After these modules have been downloaded and installed, you should download the tar.gz file containing this distribution. Once this is done decompress it, make sure all of the listed files above are in fact there and do the following steps.

NOTE:The installation of the modules above will most probably need other modules. Read the installation of each module specifically to determine what is needed

• Copy the contents of ./webchat so to that it can be found by perl when it searches for modules. In the authors case the location was: (/usr/lib/perl5/site_perl/5.005/Webchat/) for which the Webchat directory is to complete the names of the modules which are called Webchat::NAME.
• Copy the structure of scripts except for ./commandline to a path on your webserver. You will need to make sure that the directory chosen has the ExecCGI (in Apache) bit or is a script alias. Otherwise the scripts will not be accessible and not yield much result.
• Configure and execute dbsetup.plx making sure that the docs folder is either under it's path or correctly specified. This will setup MySQL and create a default superuser account for the chat system. You will need the following for this to happen:
• A working copy of MySQL (daemon active) which can be gotten here.
• Properly configured dbsetup.plx, which means looking though the first few sections under Data Members and modifying it to match your system.
• After which point you will need to create the DBM's:
• Modify Dbm.pm to make sure it points to the proper location. Currently set for /usr/share/webchat
• Create a webchat.webchat user and group and set the ownership and suid bits on the script and shared directly.
• Run the script chatadmin.plx a few times. The first time should prompt you that the files were created, the second should display all of the keys and default values. Comment out line 60 for this part. As it requires valid database information which cannot be retreived until this scripts runs successfully. When you are finished remove the comment to re-enable security.
• Change as needed. Sections should be fairly straightforward.
• NOTE: You may have problems with some version of perl. It may be prudent to make a symbolic link with whatever DBM's were created to either the equivalent name with the addition .db or without the additional .db this should correct any problems of the DBM's not being found. This problem can be seen if changing from Linux to OpenBSD
• Finally, all of the scripts including administrative scripts should be operational. Registration.plx assumes you are using sendmail, as a result people using QMail may have problems, if the sendmail wrapper is not properly configured. The author was unable to test on a QMail server.