README for Free Chat beta release 2eNotes and Installation and Setup Documentationby Bill Kendrickkendrick@zippy.sonoma.eduhttp://zippy.sonoma.edu/kendrick/Last update: 7.Jun.1998  (THIS IS A BETA RELEASE)----------------------------------------------------------------------------== CONTENTS ==This document contains the following sections, in this order:* Notes* Requirements* How to Edit Files* Installing* Turning Chat Off and On* Further Setup* Registered Users* Photos* Server Side Includes* Known bugs* Credits== NOTES ==Please also see the following files for more important information onFree Chat:CHANGES.txt		Changes to this version of Free ChatCOPYRIGHT.txt		Copyright and Disclaimer informationDISTRIB.txt		The distribution listing== REQUIREMENTS ==Free Chat is a collection of CGI's (Common Gateway Interfaces) andSSI's (Server Side Includes).  It was developed for Unix, and shoud runon any flavor of Unix.  If you are using Windows NT, please use theNT ported version of beta2d, available from the FreeChat website:http://zippy.sonoma.edu/kendrick/nbs/unix/www/freechat/== HOW TO EDIT FILES ==When the instructions in this README file tell you to edit text files,you can do this one of two ways.  Your choice will probably depend onwhat you're familiar with:(1) * FTP from the server to your computer,    * Edit on your personal computer,    * FTP back to the server    (Remember to FTP in "ASCII" or "Text" mode, not "Binary" or "Raw" mode!)or(2) * Open a "telnet" session to your computer,    * Run an telnet-based editor (like "vi", "emacs" or "pico") to edit the      files right on your server.Since you've gotten this far, you obviously know how to get files toand from your server, and how to telnet into your server account.If you choose choice #1, I suggest you use an editor like "Tex-Edit" forthe Mac or "WordPad" for Windows95.  Definitely use something whichcan load, and most importantly, save text-only (ASCII).As stated above, you should use the ASCII (or "TEXT") transmission modeof your FTP program when transfering files to and from your server andyour computer.When you are asked to search for a line of text, first remember thatthis README document usually describes which things to change in theorder that they appear in the files you are editing, so you probablywon't have to search backwards.  If you DO need to search for somethingat all, I suggest using your editor's "find" or "search" command.== INSTALLING ==To install Free Chat, follow these steps:(1) Open the file "defines.h" (located in the "src/" directory)    in a text editor.  Change the following defined values if necessary    or desired:    (Note:  When it says to "comment a line out," simply add the    characters "/*" at the beginning of the line, and "*/" at the end.)    Important options listed below are marked with a "*" on the left column.    All others are makred with a "-".*   Enter your e-mail address (or the e-mail address of whoever will be    the technical support and administrator of the chat room you're    setting up) here:      #define ADMIN_EMAIL "your@address.goes.here"*   If you are concerned about security with your chat passwords file    ("access.dat"), change the filename here, and then rename the    passwords file accordingly:      #define ACCESS_FILE "access.dat"    Example:      #define ACCESS_FILE "blank.gif"  /* Tricky filename to guess! */    and then, from a Unix shell prompt (command line):      mv access.dat blank.gif    (Note: A future version of Free Chat will support encrypted    passwords.  If you're especially concerned about people being    able to read passwords, I suggest you run Free Chat in a cgi-bin    directory, or at least moving the "access.dat" file outside of    your website home directory.  Your system administrator should be    able to help out here.)*   Comment this line out if you are NOT using System V.  If you have    problems compiling Free Chat (especially if it mentions "flock"    or "LOCK_F"), do this first.      #define SYSV    Commented, it looks like this:      /* #define SYSV */-   Set this value to the number of lines you'd like to kept around in    the chat room.  Recommended: 16 min. to 32 max.      #define MAXLINES 16-   Set this to the number of minutes a user can be idle (not sending    messages or refreshing their screen) before they are kicked out.    (Note, they will be kicked out on the next access to "chat.cgi" or    "who.cgi", so they may be "in" the chat room for much longer than    the idle time, but nobody will really see this if nobody is using    the chat room, which is when this could happen.  Ie, the last person    left without clicking the "Leave" button.)      #define IDLE 3*   Set this to "YES" if you want a constant logfile to be kept (chat.logs)    or "NO" if not.  Set to "SMALL" if you want a small logfile kept    (also chat.logs) - it will only contain "JOIN" messages, nothing else.      #define LOG NO*   Use the command "which date" from your command line to verify the    location of the "date" command.  It's very likely it's in "/bin/date",    though.  If you notice Free Chat doesn't know what time it is,    be sure to check that this is correct.      #define DATE_CMD "/bin/date"-   If you have a banner rotation program (like the "random" SSI that is    distributed with Free Chat) that you'd like to be executed    (using the "system()" function) and displayed after "chat-top.html",    specify it here, otherwise comment this line out:      #define AD_CMD "./random chatads.dat"*   If you're running Free Chat in a "cgi-bin" directory or using a    "wrapper" program, you probably can't have plain HTML and GIF files    in the same directory as the CGI's.  Fill out the path (ie, for    PREPEND, "http://site.com/chat/" and "/usr/local/www/pages/chat/"    for UNIX_PREPEND) here to tell Free Chat where to reference these files:      #define PREPEND ""      #define UNIX_PREPEND ""    Example:      #define PREPEND "http://site.com/~janedoe/chat/"      #define UNIX_PREPEND "/users/janedoe/public_html/chat/"    See the "cgi-bin and Wrapper Users" section for details...-   If you wish Free Chat to allow "internation" characters (those with    an ASCII decimal value of 0-31 or 128-255), set this to YES:      #define INTERNATIONAL NO    Be careful because some people's browsers don't understand these    characters!*   If you'd like to force all users of your chat room to be registered,    set this define to "YES":      #define MUST_BE_REGISTERED NO-   If you don't like the sizes of the frames in frames-mode, change    these values.  Be careful, though; be sure to test them after you    change them.  Note that some browsers act differently!  (ie, Netscape    versus Internet Explorer):      #define FRAME1_HEIGHT 85      #define FRAME2_HEIGHT 80-   If you wish to replace "Send", "Refresh", "Who's Here?", "Help" and    "Leave" buttons seen in the chat room with different GIF graphics,    simply replace the files in the "buttons" directory with the ones    you want, and be sure to set these #defines if the sizes of these    images aren't the same as the buttons distributed with Free Chat    (which are 80x20 pixels in size):      #define SEND_W 80      #define SEND_H 20      #define REFRESH_W 80      #define REFRESH_H 20      #define WHO_W 80      #define WHO_H 20      #define HELP_W 80      #define HELP_H 20      #define LEAVE_W 80      #define LEAVE_H 20    Note that the names of the GIFs are simply:      send.gif      refresh.gif      who.gif      help.gif      leave.gif-   If you want to turn off the whispering ("private message") feature    of the chat room, or only allow sysop- and god-level users to whisper,    set this to either "OFF" or "SYSOPS_ONLY", respectively, otherwise leave    it on "ON":      #define WHISPERING ON-   If you wish to change (or remove) the message that appears as part    of the "XYZ has joined!" when a sysop or god enters, chat, set the    text here:      #define SYSOP_JOIN_WARNING "(sysop!)"(2) Open the file "makefile" (located in the main "freechat" directory)    in a text editor.  Change the following line if the "strip" command    is unavailable on your system.    Type the command "strip" to see if it's available.  If it's not,    an error message will be displayed.       POSTPROCESS=strip    If "strip" is unavailable, change the above line to:       POSTPROCESS=touch    Note: the "strip" program simply cleans up unused code and data    from an executable (ie, the CGI's and SSI programs, in this case)    and makes for smaller program files.    If, when you run "./install" (see step 4) you get a    "src/chat.c not found" error, you may also need to change the    four values for "SRC", "OBJ", "CGI" and "SSI".  For example:       SRC=/users/janedoe/cgi-bin/chat/src/       OBJ=/users/janedoe/cgi-bin/chat/obj/       SSI=/users/janedoe/cgi-bin/chat/ssi/       CGI=/users/janedoe/cgi-bin/chat/    If you still get errors, I've found that removing or commenting-out    the "CC=gcc" line also helps.  (To comment in a makefile,    prepend the line with "#", ie: "#CC=gcc")(3) Type the command "chmod 700 install" on the command line (while    inside the main "freechat" directory created by the archive) to ensure    that the "install" script's permissions are set properly (so you can    execute the script.)(4) Type the command "./install" on the command line to run the installation    script.  It first runs the "make" command.  The program will    be compiled with the configuration you applied above.  A number    of new files will be created (and their permissions set) after    compilation is complete.  (If these files existed before, they    will not be overwritten.)    The files created are:      chat.dat		The current chat messages.      who.dat		The current chat users.      chat.tmp		Temp file.      who.tmp		Temp file.      chat.logs		A log of the chat sessions. +      banned.dat	The "banned users/IP addresses" list. *      swear.dat         The swear words file. *  Files denoted "*" are files which you may at one point be interested  in editing.  The logs file (denoted "+") you may wish to inspect.  The others are of no real use to you as an administrator.  The "install" script will then make sure the file permissions are set,  and creates a few other important files:      access.dat	A list of registered users.      robot.dat		A list of Chat Robot response rules.      convert.dat	A list of ASCII-to-GIF conversion rules.  All of these files are used for administration and personalization of  your chat room.(5) To turn on your chat room, type the command "./on Chat" from your    command line.  The following files are created:      index.html	The chat entrance page/form.  Copied from "on.html".      topic.dat		The argument(s) given to "on" will be stored here.			(In this case, "Chat".)  This is the chat room topic.                        The "./on" script does NOT reset your chat room.                        (You can change the topic by using the "TOPIC"                        command while logged into chat as a sysop- or                        god-level user, or by running "./on" again.)Now you should be able to (via HTTP) enter your chat website!  Load upa web browser and type in the URL of the chat directory on your serverand you should see a form asking for a username and e-mail address.Fill in at least a username and click the "Enter" button.  You are nowin chat!If instead you receive a "404 - Permission Denied" error from yourserver, you may need to make sure that the permissions of your chatdirectory(ies) are "755".  Use "chmod" to set it, for example:  chmod 755 /users/janedoe/public_html/chatIf you have a problem that you cannot figure out at all, feel free toe-mail me at: kendrick@zippy.sonoma.edu - note, please be sure tospecify AT LEAST the exact error message that was displayed, if any,and the URL of your chat room.== CGI-BIN AND WRAPPER USERS ==If you're running Free Chat in a "cgi-bin" directory, any GIFs or HTMLfiles directly loaded by a browser will appear broken if it tries to getthem out of the "cgi-bin" directory on your server.  (Your server willrespond that the file is not of the right type ("CGI", "PL", etc.) orthat a "Error 500: Server Error" occurred because it tried to executethe GIF or HTML as though it were a script.)To get around this, the "PREPEND" and "UNIX_PREPEND" #define's were created.When you use this, you must of course also remember to move the followingfiles and directories into the place referenced by "UNIX_PREPEND".  ad.html  index.html  buttons/  convert/  faces/  help/  photos/Note that when you do this, the "on" and "off" scripts won't workcorrectly, as they expect the "index.html" to be in the same locationas "on.html", "off.html", "topic.dat" and "nextchat.txt".To get around THIS, I suggest that whenever you turn your chat on,you copy the "index.html" that was created into the location specifiedby "UNIX_PREPEND", or make a Unix symbolic link (with the "ln -s" command,see the "ln" man. page) at the location specified by "UNIX_PREPEND" thatpoints to the real "index.html" in your "cgi-bin" directory.A future version of Free Chat will automate this and be even morecapable of EASILY handling "cgi-bin" issues...== TURNING CHAT OFF AND ON ==To turn chat off, run the "./off" command, providing the next plannedchat as the arguments (ie, "./off July 4, 1997").  The arguments aresaved to a new file called "nextchat.txt".  This file is SSI includedby "off.html".It also copies "off.html" over "index.html", replacing it.  This removesthe chat form from the page, so people know immediately that the chatroom is offline.To turn chat back on, run the "./on" command, explained above.