Whiplash IRC Client v1.4
Copyright (c) 1997-2001, Jonathan Zdziarski
All Rights Reserved

IRC OPS: Please read the section 'HOW TO TRACK AN IP' 

WHAT IS WHIPLASH?

  Whiplash is an IRC Client designed to run on a webserver, for the purpose
of allowing an HTML Gateway to chat.  I have provided this program initially
as an edicational tool, but it has grown over the years to be a great
customizable IRC client now used by thousands of website owners world-wide.
If you do not have a file named LICENSE in this archive, you may download a 
new archive containing the license from http://www.nuclearelephant.com/.
Regardless of whether or not you have read the license agreement, you are 
still bound to its terms of use, so please read it thoroughly.

  The code whiplash uses shows documented examples of the following
PERL5 areas of programming:

  - Multipart/Mixed (e.g. Server Push) Streaming
  - Sys V Interprocess Communication (Shared Memory) 
  - Socket Building and Management (using IO::Socket)
  - Using hashes to speak RFC
  - Using the SDBM Hash database
  - Signal and Process Management
  - Lexical Variable use

Other mentionable (yet non-PERL related) items:

  - Usage of CCS/Style Definitions (for background text)
  - Javascript scrolling

REQUIREMENTS:

  - Perl 5.0 or later
  - Some web server software (This was developed and tested under Apache) 
  - Knowlege of file permissions and modes, and other general knowlege you
    will need to get these scripts moving. 

ALSO RECOMMENDED:

  - A unix system with a system shared memory queue facility
  - root privileges on your system (if you plan on using whiplash's
    ident encapsulator)

TO INSTALL:

  I assume you've already uncompressed it since you're reading this.
  Make sure all .cgi files are executable (755 or whatever).  Make sure
  the pidtable.* files are all writable by the web user (e.g. group
  writable, or owned by the web user), and the same for irc.log and the 
  tables directory itself.

  Just install it in a directory that has execute permissions and is reachable
  via a HTTP request, and go to that directory. 

  You may need to change the path to perl in all .cgi and .pl files to
  reflect the path to your copy of PERL 5.

  *NOTE* You will need to make sure that the directory you are putting it
  in has "Execute" permissions in your web server configuration..otherwise
  you will get plenty of errors.

CONFIGURATION:

  The master configuration file is called '.config' you can edit some
  basic variables in this file (the file is commented with explanations)

  You can also configure most of the display colors, and some messages
  by editing the .rfc1459 file.  The .rfc1459 file is a token/key flat
  file that is turned into a hash database by whiplash upon loading.
  PLEASE NOTE: This file contains necessary control characters.  Only use
  an editor that supports control characters such as 'vi'.

EDITING THE .rfc1459 FILE

  The .rfc1459 file has up to three fields, separated by the | character.

KEY  VALUE
----------
JOIN|<FONT COLOR=#0000FF>* %HANDLE (%ADDRESS) has joined %CHAN</FONT> 

  The above value will be printed when the client receives a JOIN message
from the server, for example.  %HANDLE, %ADDRESS, %TO, %NICK, and %CHAN 
are tokens that will be replaced with the values of handle, hostname,
nick to, your nick, and channel, before it is actually printed.
  Other tokens include %x% and %x where x = the parameter number.  %x will
be replaced by the parameter #x it receives from the server.  %x% will
be replaced by the parameter #x to the end of the line.

  Any keys that begin with a / are commands.  You can modify and
define your own commands easily...

KEY  SERVER CMD                                DISPLAY RESULTS
--------------------------------------------------------------
/PIE|PRIVMSG %CHAN : ^AACTION throws a pie at %2|* %NICK throws a pie at %2^A 

In this example, if someone types /PIE, SERVE CMD will be sent to the
server (Read your rfc dox), and DISPLAY RESULTS will be what is
printed to the local client's screen.  

/JOIN and /PART do not exist in the .rfc1459 file because they have
been internally coded into the software, so that you can toggle,
through the .config file, whether or not joining/parting channels
is allowed.

Please note that ^A represents CTRL-A in the file.  If you wish to add
lines, you will need to learn how to insert control characters into your
editor.  In 'vi', you hit Control-V and then type th econtrol character
to insert.  I was going to make it interpolate control characters, but that
causes problems with the translation of people who use ^ in messages or
in their handles.

CONTACTING ME

  This project is now defunct.  No support is available.

KNOWN BUGS (Told you it had some)

  - The scroll() command for netscape v3.0 is causing the screen
    to jump all over the place, and as makes it hard to chat.
    If there is some javascript way of determining the bottom
    if the window's pixel number (before the page is finished loading),
    or another way to scroll to the bottom of a window, please let me know.
  - Using the MSIE Userlist, if the socket control script (nph-irc.cgi)
    should load and attempt to update the userlist before the
    msie-userlist.html file loads (which happens occasionally over slow
    connections), javascript errors may be reported.  I've added a small
    line in the javascript to test if self._fuserlist.document.all.text != 
    null, however this only works in MSIE.  In other cases, the
    script will report a 'Access Denied'.  If anyone knows a way of turning
    off Javascript errors please let me know.  Once the userlist loads,
    it will be updated the next time somebody joins/leaves/mode changes or
    by typing /NAMES to redisplay the userlist. 

A NOTE ON SHARED MEMORY/SYSV IPC:
Shared Memory does not work on all platforms.  It's been
reported that it does not work on some BSD platforms, as most BSD
platforms do not support Sys V IPC. I've thoroughly tested it under
Solaris, and had no problems.  Use the unix command 'ipcs' to take a look
at your shared memory queue.  It should also tell you whether or not
shared memory is supported on your system.  IF YOU DO NOT HAVE AN
OPERATING SYSTEM THAT SUPPORTS SHARED MEMORY, you may either search for
an extension to add it to your kernel, or you may set the $USE_SHMEM
variable in .config to 0, which will cause whiplash to use plain 
textfiles in place of shared memory (Also set $MEMDIR).

A NOTE ABOUT MEMORY LEAKS: In 1.2b1, there were several leaks generated by
the fact that not all operating systems report a HUP or INT signal to the
process if the user leaves the page or shuts down their browser.  As a result, 
I added a small bit of code that reports each shared memory key, and pidfile
of the script to a hash database (and will remove it from the database
if the script's cleanup subroutine gets called).  If it does not get called
and the script dies, the program shmclean.pl reads through the database, tests
all the pids, and removed the keys of the dead pids, deallocating the memory.
This SOLVES ALL MEMORY LEAK PROBLEMS as far as this script is concerned.
The shmcleanup.pl script is run every time login.cgi is run.  If you use this
code publically and have several people using whiplash, it would be advisable
to remove it from login.cgi and run it as a cron job.

HOW TO TRACK AN IP: Whiplash makes every effort to allow IRC OPS to be
able to track down and ban abusers of whiplash using three different
methods.  Please take a moment to look at the output of a /WHOIS
on a whiplash user...

** WHOIS: "Krioni" * Unknown (3466298169) (CE9B8339@elijah.jesuscafe.com)
** WHOIS: Krioni #CGI 
** WHOIS: Krioni on irc-w.frontiernet.net (Frontier GlobalCenter IRC West
Server )
** WHOIS: Krioni 80 Seconds Idle
** End of WHOIS List **

METHOD 1: IDENTD: If the webmaster is running the IDENTD encapsulator that came
with whiplash, the IP address of each user will be encapsulated into a
hexadecimal form as their IDENT.  The CE9B8339 as the IDENTD is a hexadeximal
representation of the IP address the user is connecting from...for example...

[CE]  [9B]  [83]  [39]
206 . 155 . 131 . 57

As a result you can easily translate the IP and ban either the entire
IP or their Class C...for example CE9B83*!*@elijah.jesuscafe.com or
some variation thereof should ban anyone in that Class C.

METHOD 2: 32-Bit IP Address: The 3466298169 in the first line of the
WHOIS output is a 32-Bit representation of the user's IP address.  This is
displayed whether or not the webmaster is using the ident encapsulator.
You can translate this address token into an actual IP address by
using a /dns -h 3466298169 command.  Unfortunately, this method does not
allow you to ban as method 1 does, but does allow you to translate the IP.

METHOD 3: CTCP: When you CTCP a whiplash user for USERINFO, it returns their
full IP address.  This is the easiest way to obtain it.

HISTORY

1.4.1
- Fixed 'fixed-width' again; was set permanently to fixed-width
  (login.cgi fixed; index.html was midding a bracket)
- /ME commands (and others) were not showing up on local screen
 
1.4
- Rewrite of variable structure; all variables now lexical
  (For use with mod_perl, fix memory leaks, etc)
- Ported original Socket.pm code to use IO::Socket for better compatibility
- Fixed several SDBM_File untie routines, which may speed up server or
  at least run irc processes with more resources
- Added automatic registration process
- Fixed 'fixed-width'; it was not working 

1.3.3e
- Documented Tracking/Banning methods
- Renamed the IDENTD Spoofer to the IDENTD Encapsulator - better description
  and it prevents people from thinking it's designed to compromise security
- Modified scrolling javascript to work on a Macintosh w/Netscape 
  (still requires some tweaking)

1.3.3d
- Added $IDENT_METHOD option allowing you to either send the person's
  nickname as their IDENT or the hex equivalent (e.g. CF1F58F8); the hex
  is very useful for IRCops who want to ban a whiplash user without banning
  the entire server.

1.3.3c
- Replaced <FONT> codes with mIRC color codes in the RFC file
  and in the source code.
- Added control character parsing to the rfc file and output
  subroutine. (e.g. ^A is translated to a CONTROL-A, rather than having
  to have a control character hardcoded.  Please be careful with case.)
- Fixed a few more RFC's (KICK, INVITE, KILL)
- Added @DISALLOWED_CHANNELS allowing you to block out certain channels
  from being joined (uses regex matching)
- Used PERL5's hostname.pl rather than unix's directly (although they
  do just about the same thing)
- Fixed a problem where the wrong long int was being reported to represent
  the user's IP address in WHOIS.

1.3.3
- Added IDENT Encapsulator (requires root privileges on server)
- Implemented OUTGOING DCC CHAT Capabilities using IO::Socket
  Make sure you have a fully qualified, DNS confirmed hostname.
- Moved pid and ident tables into the 'tables' directory

1.3.2
- Implemented DCC CHAT Capabilities (INCOMING ONLY). 

1.3 (Release)
- Now returns CTCP PING, USERINFO and VERSION.  CLIENTINFO, FINGER, and other
  methods of CTCP can be easily implemented into the code, however
  have been left out because they're, for the most part, not used.
  PLEASE NOTE: CTCP USERINFO Returns the user's IP Address (for
  abuse handling purposes)
- Added STYLE and COLOR CODE PROCESSING (mIRC Style).  Since web browsers
  don't handle inverse fonts and inverse text well, reverse as well as
  reverse codes are ignored unless you have a browser > v4.0 that
  supports the <STYLE> formatting.  If you have a browser < 4.0,
  the backgrounds and inverse will not be displayed, which could make
  some variations hard to read on your browser.
- Added color code hash to .config
- Added a 'fixed-width font' option allowing the client to choose whether
  they want to use a variable width font or not
- Implemented a /CLEAR function that will work only in Netscape
- Caused incoming CTCP's to be displayed properly
- Made some aesthetic changes to the RFC Control File
- Fixed more DALnet RFC
- Added the stripping of ^M's to the parse subroutine (DALnet uses ^M's
  instead of \n's causing the userlist to malfunction)
- Fixed a minor bug causing a mode -o+b anything to put that hostname
  on the userlist (some bots use -o+b).  Fixed this by making sure
  the name existed before changing its' mode.
- Added the following commands: /WALLOPS /CLIENTINFO /LUSERS /MOTD
  /USERHOST (aliased to /DNS)
 
1.3b4
- Replaced &1 with %HANDLE and &2 with %ADDRESS in the RFC Control File
- Made a MAJOR bugfix in the RFC parser.  All RFCs should be working
  properly now including the KICK, etc.
- I've incorporated the MSIE and NETSCAPE code for the userlist into the
  same nph-irc.cgi script (because it was very time consuming to make updates
  to the code twice), and have created a userlist_msie/uselrist_ns 
  subroutine that is called depending on your browser type.  This makes
  it *much* easier to upgrade the code.
- I've removed $handle and $to from the RFC array, since they have their
  own variables now (%HANDLE and $TO).  As a result %1 = the very first
  word in $msg.  As a result of this, I've modified the entire .rfc1459
  file to reflect the new values.
- Carried $BROWSER over using form variables, rather than calculating it
  each script
- Fixed the < and > substitutions to work (didn't need backslashes)
- MSIE All-text-in-blue problem fixed (left out a > in the BODY)
- Added < > parsing for usernames in the user list (some IRC Clients
  allow < > in usernames)
- Added PONG to the RFC Control File
- If no parameters are given with a particular command, all :'s are
  stripped from the RFC Command Line.  This is to allow /TOPIC, /AWAY, and
  other commands that don't necessarily require parameters to work properly.

1.3b3
- Fixed 'defaults' from .config to work
- * MSIE USERLIST NOW SUPPORTED * 
  IMPORTANT: MSIE Does not process x-mixed-replace protocols correctly,
  causing the original userlist to break in MSIE.  Unfortunately the
  only way to maintain a userlist in MSIE is through the use of javascript.
  Due to popular demand, I've added userlist support to MSIE using javascript,
  HOWEVER, I have split up the nph-irc.cgi script into two separate
  scripts (one for netscape and one for MSIE) for the following reasons:
      a. My goal is to teach PERL, not Javascript; to teach server
         streams, not cheap dhtml copouts.  The proper way to maintain a
         userlist according to these goals is to use the x-mixed-replace
         content header.  I wanted to keep the proper programming example
         the main part of the course code, which is still used with all
         netscape browsers.
      b. I could have made netscape use this as well, however it would have
         caused the userlist to break with Netscape 3.x.  I'd quite
         frankly rather segregate my code than bow to and ultimately 
         condone the poor programming Microsoft has done on part of its
         browser.  Not to mention most people still use Netscape 3.0.
      c. With the programming being different, and also incorrect, I want
         to draw a fine line between the 'right' way to do things and
         the 'wrong' way.  Some may disagree and believe javascript
         is the way.  To those of you who believe that: go away.
      d. Separating the two scripts results in having two small pieces of
         code, rather than clumping the whole thing into one big script
         results in mildly faster execution, and much less confusion for
         students of this code to learn.
  What does all this mean?  It basically means that microsoft messed up
  royally when they wrote some parts of MSIE, and as a result, modified
  code is required to get it to run properly.  This modified code is
  evil, and therefore must be separated from the good code.

1.3b2
- Fixed whiplash to work with MSIE again (previously it was broken in 1.3b1
  because it was waiting for a ready from the userlist process that never
  existed)
- Implemented $USE_SHMEM in .config, which when set to 0, will use
  textfiles (the old way) to transfer information (since not all machines
  support shared memory).  If you do this make sure you set $MEMDIR. 
- Added <CODE> tags to the userlist to make it fixed-width

1.3b1
- Added a realtime userlist for netscape users (using a second shared
  block of 4k).  Unfortunately, the multipart/mixed content type in MSIE
  doesn't appear to have a boundary whereby it will clear the box.  Perhaps
  there's a javascript command to do it.  I will be looking into other ways
  of implementing this on MSIE before releasing 1.3 (final).
- Caused $nick to be updated if the user changed their nickname prior to
  registration (v1.2.2 Rev B's modification only updated it post-registration)
  This solves all problems with private messages showing up as <user>
  instead of **user**
- Added the following commands to the rfc hash:
  /VOICE /DEVOICE /OP /DEOP /DOP

1.2.2 Rev B
- Identifies CTCP Pings (Still does not respond)
- Changes $nick when user changes their handle (this solves part of the
   problem with private messages showing up as <user> instead of **user**)
- Moved 'NICKNAME ALREADY IN USE' to the RFC hash
- Added the following commands to the rfc hash:
 /BANLIST /BAN /UNBAN /INVITE /PART /VERSION /LINKS 

1.2.2
- Improved the Javascript SCROLL routine for Netscape v4.0
  to use scrollBy() instead, which prevents jumpiness.
- Made login.cgi register the IPC Key in the pid table
  as well as nph-irc.cgi, so that in the event login.cgi never
  calls nph-cgi.irc, it will still be removed from shmclean.pl

1.2.1
- Fixed a but in nph-irc.cgi which exited upon performing a JOIN.
  Several / Commands also resulted in submit.cgi timing out,
  because the shared memory was never reset to 'listen' state.
- Removed the || die from shmclean.pl's semctl line to prevent
  it from exiting if an IPC ID happens to be nonexistant (e.g. 
  a reboot)
- the < and > were translated backwards (&gt and &lt).  This made
  <'s appear as >'s and vice-versa.  This is now fixed.
- Actions now work (/ME) !  I finally got the RFC on how to do
  it from someone in #perl.  
- Implemented /CTCP (Syntax: /CTCP (nick|channel) [message]
- Added a new variable in the .rfc1459 file (%NICK) which was
  needed for /ME actions.
- There was a flushing problem that caused some data to never
  be displayed.  This was a result of using \n instead of \015\012
  and not using \n in one place.  This is fixed.

  *  This fixed a lot of the 'echo' bugs and whatnot.

1.2
- Added a SDBM Hash and a cleanup script to clean up *ALL*
  shared memory leaks.  This script is run from login.cgi,
  however you can make this a cron job fairly easily.
- chomp'ed $TIME to prevent the logs from having an extra
  carriage return in them
- Identified CTCP PING's from users (but still does not
  return them)

1.2b1
- Replaced the txt/pids directories with SysV IPC Shared Memory
- Added $PRIORITY to the configuration

1.1a

- Cleaned up the source code a lot
- Added 265 and 266 to RFC including some other obscure codes
- Added .config master config file
- Added default server settings
- Added ability to /JOIN to another channel (toggle in .config)

1.0

- Added HTMLized Color/styles
- Created .rfc1459 Hash Key
- Genesis

REV 0409.100