e_Chat 4.1 Set Up

(NT users also check out nt.txt.)

Thanks for purchasing e_Chat. I think you will find this
script to be one of the best blends of usability and
efficiency on the Net. It requires a bit more set up than
other scripts, but if you've successfully installed other
cgi scripts, you should have no problems.

If you want me to install this script for you, contact me at
support@e-scripts.com for details.  The cost is $39.95.

A.) New Features

B.) File List

C.) Setup

D.) Additional Instructions and tips

E.) Troubleshooting


-----------------------------------------
New Features - in 4.1

- Functions and pages work the same in MSIE and NS.

- Most users can't back into room once they've logged off.

- Improved Server Push function (with addon.)


 New Features - in 4.0a

- Vastly simplified setup.  No renaming of files needed.

- Password protection added to admin.

- Simplified setup of extra permanent rooms.


New Features - in 4.0

- Kinder, gentler, security functions.

- Smilies, if you want them.  They only appear at the end of
a message.

- Better integration with Addons.

- Simpler setup, each variable need only be entered once,
and setup41.cgi is included to simplify installation.

- If anyone attempts to log on with a registered
nickname(without adding the password to the nickname - see
below), they get a form asking for the password.  For the
truly clueless.


B.) File List

NOTE: The files common to all rooms are found in the
"echat41" directory. The files for each separate room are
stored in subdirectories of this directory. (The room
included with the files you downloaded is called "public.")


YOUR "cgi-bin/echat41" DIRECTORY CONTAINS:

echat41.cgi. ~ The primary chat script. It should be put in
your cgi-bin directory, and run under cgiwrap if available,
to guard against hackers viewing this file.  Your provider
will have details on how this is done.

admin41.cgi - Performs the administrative functions. This
script should also be protected (see above).

lister41.cgi - This script sends users their logon page,
including the occupants list in place of the line *list*.

setup41.cgi - Automated setup script.


YOUR "public_html/echat41" DIRECTORY CONTAINS:

index.html (empty) - This is an empty HTML page that keeps
people from seeing your room subdirectory names.

readme. txt - This file.

various *.gifs - The smilies.


YOUR "public_html/echat41/public" SUBDIRECTORY CONTAINS:

index.html - contains the frameset for the frames version and
also includes a link in the <NOFRAMES> section) to the
framefree log on. This frame also includes Javascript, so
you shouldn't change these frames (see index.html).

frsample.html - A frameset illustrating how extra frames can be
added to e_Chat.

messages.html - This page stores and displays the chat
messages. (IRC format)

rmessages.html - This page displays the messages in reverse
order. (WWW format)

chatform.html - This is the log on form that appears at the
bottom of the frames page. This page is the "cookies"
version.

help.html - This page is displayed with the log on form.  It
explains how to log on, and includes some info about the
chat.  It also displays occupants if called via
lister41.cgi.  Do not edit or remove the line '*list*'.

help2.html - This page is displayed when the [Chat Tips] link
is clicked. It describes the various user functions.  This
page is plain HTML, and can be edited freely.

ffhelp.html - This is the framefree log on page.  It is
displayed via lister41.cgi.  Do not edit or remove the line
'*list*'.

admframe.html - This is the frameset for the chat
administrator.

admin.html - This is the page that appears in admframe.htm
frameset, and displays the admin form.

header.html - The top page of the user frameset.  Includes
the name of the room. This page is plain HTML, and can be
edited freely.

chatters.txt - (created during setup) holds user data.

log.html - (created during setup) Keeps a copy of each message
that is sent to the room.  It also stores each users remote
host info.


C.) Setup

echat41.cgi includes a CONFIGURATION SECTION and an OPTIONS
SECTION. CONFIGURATION is the important stuff, and is
described below. The OPTIONS set the various customizable
features of e_Chat, and are described within the scripts
themselves.  Except for the password in admin41.cgi, the
other scripts include OPTIONS only, and require no
configuration to function.

1.) echat41. cgi -

a.) Top line (path to perl) - should probably read
#!/usr/local/bin/perl or #!/usr/bin/perl, depending on the
location of perl on your server. (Just check your other perl
scripts and match them.)  NT users can ignore this.

b.) $filepath - The path to your "echat41" directory (Ex. If
the complete path to your 'public' subdirectory is
/usr/domain/echat41/public, then $filepath =
'/usr/domain/echat41' . DO NOT INCLUDE A TRAILING SLASH.

c.) $fileurl - The URL of you parent directory.

d.) $exiturl - The full URL that the user is directed to at
log-off.

e.) @valid - valid referring URLs (your domain name, with
and without the www.)

f.) $perma_rooms - Your list of permanent rooms.  The first
one should always be 'public'.

2.) All other cgis -

a.) Make sure the top lines are all the same as echat41.cgi.

b.) Be sure to set your password in admin41.cgi.

3.) Upload and set permissions (NT users ignore the
permissions stuff).

-----cgi-bin
--------echat41 subdir ---- chmod 777 (rwxrwxrwx)
------------echat41.cgi --- chmod 755 (rwxr-xr-x)
------------admin41.cgi --- chmod 755 (rwxr-xr-x)
------------lister41.cgi -- chmod 755 (rwxr-xr-x)
------------setup41.cgi --- chmod 755 (rwxr-xr-x)
----public_html
--------echat41 subdir ---- chmod 777 (rwxrwxrwx)
------------index.html ---- chmod 644 (rw-r--r--)
------------public subdir - chmod 777 (rwxrwxrwx)
----------------messages.html -- chmod 666 (rw-rw-rw-)
----------------rmessages.html -- chmod 666 (rw-rw-rw-)
----------------index.html ----- chmod 644 (rw-r--r--)
----------------ffhelp.html ---- chmod 644 (rw-r--r--)
----------------admframe.html -- chmod 644 (rw-r--r--)
----------------admin.html ----- chmod 644 (rw-r--r--)
----------------chatform.html -- chmod 644 (rw-r--r--)
----------------header.html ---- chmod 644 (rw-r--r--)
----------------help.html ------ chmod 644 (rw-r--r--)
----------------help2.html ----- chmod 644 (rw-r--r--)
----------------index.html ---- chmod 644 (rw-r--r--)

4.) If your cgi files are in your cgi-bin directory, you
can skip this step, and go to step 5.  If they're elsewhere,
you need to change the URLS in the forms in the following files:

index.html
admin.html
ffhelp.html
chatform.html

The string /cgi-bin/ needs to be replaced by the relative
(or complete) path to your cgi scripts.  There are three
URLs in index.html, and one in each of the others.

5.) Run setup41.cgi.  This script will create the rooms
listed in $perma_rooms.  It will also create reglist.txt,
banlist.txt, and chatters.txt files.

6.) Set permission (NT users ignore).

-----cgi-bin
--------echat41 subdir ---- chmod 755 (rwxr-xr-x)

That's it!  Type in the URL to index.htm, which is in the
directory of the room you want to enter, and you're there.
The URL for the public room is:

http://www.domain.name/echat41/public/index.htm

Your admin frameset for the public room is:

http://www.domain.com/echat41/public/amdframe.htm



******************File Locking******************

You'll find a variable ($lockon) in the OPTIONS section.
It's set to 'no'. After your initial testing is complete.
and the room is running, set this to 'yes' . If you get an
error, it means that you can't run file locking on your
server. But if your script continues to work, you have
enabled file locking, and you're less likely to experience
write errors in a busy room.


D.) Addition Instructions and Tips

User Functions -- users can:

1.) choose a text color ~- Users seem to enjoy this feature.
I included it because it makes it a lot easier for the eye
to follow the conversation as it scrolls down (or up) the
page.

2.) view messages as they scroll down from the top, or up
from the bottom. Users of other types of chat, like AOL or
IRC, will appreciate this option.

3.) send private messages to other users, or they can ignore
private messages if they prefer.

4.) become registered users, and own their nickname and
display a custom log on message.


Administrative Functions -- site's owner can:

NOTE: You  must enter your admin password in the box in the
top frame to enable admin functions.

1.) designate "Registered Users", who own a particular
Nickname and have a custom log on message. (See below.)

2.) Ban users (via remote host name). Three mouse clicks and
any offender is unable to send messages or log on. The
remote host data remains in the banlist.txt file until you
edit it. (The remote host variable is a text equivalent of
the user's IP and is more specific than the domain name.)

3.) Edit the banlist to ban by domain or partial remote host
string. Essential for quick permanent banning.

4.) A click of your mouse clears the messages window.  This
function now fixes a busted page as well.

5.) Eavesdrop on a room without logging in.

6.) A log is automatically kept of messages. This log can be
viewed from the admin frame, copied as text or html via your
browser, and deleted.  You can opt for an abbreviated form
of the log, just including log-ons, log-offs, private messages,
and messages with %naughty words.

*NOTE: The admin functions require frames. Each room has its
own admin page, and there's no master admin page for all
rooms.  However, all rooms share the same registered users
and banlist.


***************Registering Users*****************

To register a user, add their info to the list by clicking
the [Edit Reg Users] button in the admin frame.  Each entry
 should be in the form:

nickname*password*log on message

Like:

Mb*perlman*Hi All!!

Once you've registered a user, they can log on by entering
the following in the Nickname field:  nickname*password.  No
punctuation other than the *. They will log on, and their
nickname and custom log on message will appear. Anyone else
attempting to use any registered nickname will get a form
requesting the password.

***********Tips on User Functions*************

[Reverse Mode] - This loads the reverse message page.  This
works best with Netscape. NOTE: If you're running in 'low'
mode, this option is not available, and the reverse message
page is not written to.  Note: If you're running the server
push mode, this link will not work for every browser, since
it initiates the Server Push mode, which not all browsers
can display.

***********Tips on Admin functions************

[Eavesdrop]  Allows you to view the chat without log on.

[View Log] - displays the current log with new messages
added at the bottom. You can save the page locally via your
browser as text or HTML.

[Clear Log] - Clears the current log file.

[Clear Chat] - clears the message file.

[Ban User] - displays a form listing current users. Select a
name and click "Ban User." The offender will be "logged
off," and unable to return to the chat.

[Edit Banlist] - displays a text box, allowing you to edit
the banlist. You can delete individual entries, or you can
edit the users REMOTE_HOST string to ban by part of the
string, or by Domain (See below).

[Edit Reg. Users] - displays the registered user list, and
can be updated directly from the form.


******************TIPS ON BANNING***********************

Banning by REMOTE HOST will prevent the offender from
returning to the chat immediately, but they might be able to
re-enter if they disconnect/reconnect to their provider,
since they now have a slightly different REMOTE_HOST string.

You can make the ban permanent by editing offender's REMOTE
HOST string to whatever part of that string remains
constant. For example, you could edit the string down to the
domain part. (Ex. compuserve.com) Since the domain is always
part of the REMOTE HOST string, the user is permanently
banned. Of course, so is everyone else on Compuserve!

Sometimes the REMOTE HOST string includes the name of a city
(Ex. ad80-589.kansas-city.worldnet.att.net.) You could edit
down to the "kansas-city.worldnet.att.net" part. The ban is
still permanent, but you' re only excluding the offender and
users from Kansas City that use ATT.

On some servers, the REMOTE HOST string is not returned, and
you have just the user's IP. (Ex. 123.254.2.99) You can
still ban using IP, and there's a possibility that it's
static (unchanging), so the ban is permanent. If you want to
shorten the IP, leave the first two numbers. They're usually
the equivalent of the domain.

Unfortunately, there's no perfect solution here, and it's up
to you to decide what's preferable: excluding no one,
including trouble-makers; or banning those offenders, and in
the process running a slight risk (~ 1%-10%, if you ban by
domain) of excluding an innocent person from your chat.
However, editing does help keep that chance as low as
possible.

************TO ADD PERMANENT ROOMS:***********

Just add the room names to $perma_rooms in echat41.cgi, and
run setup41.cgi.  In order to delete rooms created this way,
you need to install mkroom41.cgi, and remove the relevant
room names from $perma_rooms.  See the readme for
mkroom41.cgi for details.

********OPTION notes for echat.cgi************

These are some of the extra variables in the CONFIGURATION
SECTION of echat.cgi:

$timefix - Allows you to add to or subtract from the hour
part of your server's displayed time. (Can be a positive or
negative number.)

$chat_help, etc. - Allows you to change the text of the
generated links, or replace those links with images, if you
prefer.

$mode - Sets the "speed" of the chat. Leave as is ('high'),
unless your provider complains, due to a slow or overworked
server. If set to 'low' , the chat refresh rate will slow,
there will be no [Netscape Mode] option, and the log will
only store log-ons, log-offs, and statements including
%naughty words. These changes will significantly reduce
server load, without eliminating any essential chat
function.

$1ightsout - If 'yes', the last user to log out will trigger
a message clear.

$1ockon - See "File Locking," above.



Lastly, there is a lot of HTML in echat.cgi. However,
there's also a lot of Javascript, which is tricky stuff
compared to HTML.  You can edit header.html and help2.html all
you want.  You can also edit help.htm, and ffhelp.htm, as
long as you leave the *list* line alone.  Finally, you can
edit the <body> tags for both of the other frames in the
OPTIONS SECTION of echat.cgi.  However, if you make any
modifications beyond these, you're on your own.


E. ~ Troubleshooting

1.) If you're having trouble getting the chat working, check
out the follow resources: (99% of the setup problems
reported to me by users can be solved by following the tips
found here.)

http://www.webreference.com/programming/perl/lOl/

http://www.teleport.com/~gerth/CGI/Perl_Editors.html


2.) If you get a 'Permission Denied' error, this indicates
that one or more your URLs are not displaying the same
domain, which is considered a security violation if
Javascript is involved.  You need to examine all URLs
associated with the chat system, and make sure they match.
Common errors are:

Leaving off the www part.

Using numbers for some URLs, and text for others.

Mixing lower case and upper case domain names.

------------------------------------------------------------
---

Thanks Again!

Mb
