+--------------------------------------------------------+
| LogScribe - Your Web Statistics Solution               |
+--------------------------------------------------------+
| by Usama Wazeer (usamaw@cs.utexas.edu)                 |
| and Daniel Cedras (cedras@texas.net)                   |
| original concept by Matt Kruse (mkruse@netexpress.net) |
| made Y2K ready by Kevin Cozens (kcozens@interlog.com)  |
+--------------------------------------------------------+
NOTE: YOU MUST BE ABLE TO RUN CGI SCRIPTS OF YOUR OWN IN 
      YOUR ACCOUNT TO RUN THESE SCRIPTS AND YOUR MACHINE 
      MUST HAVE A PERL COMPILER (VERSION 5.x prefered) 
      INSTALLED ON IT. EMAIL YOUR WEBMASTER OR SYSTEM 
      ADMINISTRATOR TO FIND OUT IF YOU HAVE PERMISSION TO 
      RUN YOUR OWN CGI-BIN'S AND IF SO, WHAT DIRECTORY 
      THEY SHOULD BE INSTALLED IN AND HOW THEY SHOULD BE 
      CALLED FROM AN .HTML FILE. TYPING: perl -v  AT YOUR 
      UNIX PROMPT WILL TELL YOU WHICH VERSION OF PERL YOU 
      HAVE INSTALLED (IF INSTALLED) YOU MUST ALSO HAVE A 
      BROWSER CAPABLE OF SUPPORTING TABLES IN ORDER TO 
      SEE THE LOGS



-=INTRODUCTION=-
----------------
Any question you may have about LogScribe may have an answer
in the faq.txt that accompanies this readme.  If not, contact
the authors.



Contents
--------
readme.txt          - this file
faq.txt             - frequently asked questions - troubleshooting
changes.txt         - what has changed from previous versions
config.pl           - main configuration file
makelog.pl          - adds entries to the log file
showlog.pl          - outputs a graphical representation of accesses
pagelog.pl          - outputs last connections in a listing format
logscan.pl          - basic tool to scan/fix log errors
dot1.gif            - gif used in the graphs
dot2.gif            - "   "    "  "   "
dot3.gif            - "   "    "  "   "
dot4.gif            - "   "    "  "   "



-=INSTALLATION=-
----------------

Instructions 
------------
note: we will create a logscribe directory inside our cgi directory so
      that we can move all our scripts (*.pl) in there. Some users aren't
      allowed to run scripts inside a subdirectory of the cgi directory,
      In that case they can move all their scripts (*.pl) to their normal
      cgi directory and disregard any reference to the 'logscribe' directory
      mentioned below.

- create a 'logscribe' directory inside your cgi directory

- move these files into the 'logscribe' directory:
   -> makelog.pl 
   -> pagelog.pl 
   -> showlog.pl
   -> logscan.pl
   ->  config.pl

- make your logscribe directory READABLE/WRITABLE/EXECUTABLE to the server
  by typing: chmod 707 logscribe     or   chmod 707 .   if inside of it
  (the same rule applies to your normal cgi directory if you can't have a 
   subdirectory in it)

- make the scripts (*.pl) READABLE/EXECUTABLE by typing: chmod 705 *.pl

- edit config.pl using a text editor like pico and configure it to your
  liking. I STRONGLY suggest you put the full path and full URL to files
  when asked for them. If you don't know what your full path is, while
  inside your logscribe directory (or cgi directory if that's where
  your *.pl files are) type: pwd  and hit ENTER.  If that doesnt work
  try typing: echo $cwd  and hit ENTER.  Use that path and append the
  filename to it after an additional slash... if path is:
  /home/users/cedras/public_html/.cgi-bin/logscribe   
  and that's where you want your access.log to be, as a path you would 
  enter:
  /home/users/cedras/public_html/.cgi-bin/logscribe/access.log

- move those gif files to your html directory:
   -> dot1.gif 
   -> dot2.gif 
   -> dot3.gif
   -> dot4.gif

- make them readable by typing: chmod 604 dot*gif


+=====================================+
|   visual representation of setup    |
+=====================================+

LEGENDS
=======
"" = user's account root directory (usually his/her login)
{} = a directory
() = permission bit set on file or directory as viewed with ls -l command  
[] = command to set those bits
=======


  "cedras" (rwx-----x) [chmod 701]
     |
     +----{html} (rwx---r-x) [chmod 705]
     |      |
     |      +--dot1.gif (rw----r--) [chmod 604]   
     |      +--dot2.gif (rw----r--) [chmod 604]   
     |      +--dot3.gif (rw----r--) [chmod 604]   
     |      +--dot4.gif (rw----r--) [chmod 604]   
     |
     +----{cgi} (rwx---rwx) [chmod 707]
            |
       {logscribe} (rwx---rwx) [chmod 707]
            |
            +--makelog.pl (rwx---r-x) [chmod 705]
            +--showlog.pl (rwx---r-x) [chmod 705]
            +--pagelog.pl (rwx---r-x) [chmod 705]
            +--logscan.pl (rwx---r-x) [chmod 705]
            +---config.pl (rwx---r-x) [chmod 705]



-=SETING UP AND RUNNING=-
-------------------------

As mentioned previously, there are 5 perl scripts each with a particular
function:

makelog.pl  -  adds new entries to your log file in a format that can be
               read and used by showlog.pl and pagelog.pl
showlog.pl  -  shows all the statistics about connections to your pages in
               graph formats
pagelog.pl  -  shows all the connections to your pages in a listing format

config.pl   -  main configuration file for all the scripts.  This is the only
               file you have to configure (hopefully) in order to run logscribe
logscan.pl  -  a very basic script to look for erroneous entries in the log
               file caused by program execution errors.  It can also help u
               repair those entries

Logging a page
--------------
Whenever you create a web page whose access you want logged, insert the 
following tag in it:

<IMG SRC="url_to_makelog.pl?name_of_page_to_log,url_to_page_to_log">

of course, substitute the url to the script (makelog.pl) with yours (it may 
be different from the actual Unix path to it - that's why you have to ask 
your system administrator how to call up (reference) the cgi-scripts from an 
html file), replace the name_of_page_to_log with the name of the page you
want to log and substitute the url to that page with yours of course.

If the 'name_of_page_to_log' has spaces in it, replace the spaces by the
'=' sign which will be automatically replaced by a space later.

example of a tag:

<IMG SRC="http://www.texas.net/cgi-bin/user/~cedras/logscribe/makelog.pl?
  My=Guestbook,http://www.texas.net/~cedras/guestbook.html">

IMPORTANT:MAKE SURE THERE IS NOT A SINGLE SPACE ANYWHERE WITHIN THE QUOTES
          AFTER SRC=  AND MAKE SURE NEVER TO HIT ENTER TILL YOU GET TO THE
          VERY LAST '>' OR ELSE I GUARANTEE ALL HELL WILL BREAK LOOSE !!!
          (note: in the example above I hit ENTER after 'makelog.pl?' just
                 so that my example fits nicely on your screen but when YOU 
                 type that tag do NOT hit ENTER anywhere in there - it must
                 all be on a single line !!!)

and that is ALL you have to do to record a page !!



-=VIEWING THE LOGS=-
--------------------

In your browser window, enter the URL to your showlog.pl 
in order to view your logs:
 ex: http://www.texas.net/cgi-bin/user/~cedras/logscribe/showlog.pl



-=DISCLAIMER=-
--------------

The non-registered version of LogScribe may be freely 
distributed subject to, but not limited to, the following 
terms: LogScribe may not be sold or resold, distributed as 
a part of any commercial package, used in a commercial 
environment, used or distributed in support of a commercial 
service, or used or distributed to support any kind of 
profit-generating activity, even if it is being distributed 
freely.

If you would like to distribute LogScribe as part of a 
shareware distribution, magazine, internet book, CD ROM, 
etc. please contact the authors for permission.

All commercial use interests in LogScribe should be directed 
to cedras@texas.net or usamaw@cs.utexas.edu

The integrity of the original LogScribe distribution files as 
distributed is essential. LogScribe and all of its related 
files must be distributed together in the original format. The 
LogScribe distribution package may not have files added to it 
or removed from it.

LogScribe is provided "AS IS" without warranty of any kind, 
either expressed or implied, including but not limited to the 
implied warranties of merchantability and fitness for a 
particular purpose. In no event shall Daniel Cedras or 
Usama Wazeer be liable for any damages whatsoever including 
direct, indirect, incidental, consequential, loss of business 
profits or special damages, even if Daniel and Usama have been 
advised of the possibility of such damages.


-=CLOSING=-
-----------

+-----------------------------------------------------------------------+
| Mucho thank's go to Larry Wall and Randal L. Schwartz                 |
| for their wonderful book "Programming PERL, 2nd ed."                  |
| an O'Reilly & Associates publication ISBN 1-56592-149-6               |
|                                                                       |
| A great big hug  to Nisha Sharma (nisha@vt.edu)                       |
| for helping us test this baby ! *smooooooch* ! :)                     |
|                                                                       |
| Enjoy and please visit our web pages as a token                       |
| of your appreciation for the efforts we put in :-p                    |
|                       Usama, Daniel, Nisha                            |
+-----------------------------------------------------------------------+
| Usama Wazeer  | usamaw@cs.utexas.edu | www.cs.utexas.edu/users/usamaw |
| Daniel Cedras | cedras@texas.net     | www.texas.net/~cedras          |
| Nisha Sharma  | nisha@vt.edu         | acm.vt.edu/~nisha              |
+-----------------------------------------------------------------------+
