------------------------------------------------
|GNU UniCount 1.4.0 by Evil(macabre@cfl.rr.com)|
|     Copyright(c) 2000 macabre@cfl.rr.com     |
|	http://unicount.linuxguru.net/         |
------------------------------------------------
|                                              |
|Table of Contents:                            |
|------------------                            |
|                                              |
|1) About                                      |
|	- 1.0 - General                        |
|	- 1.1 - Multiple Document Support      |
|	- 1.2 - Multiple Website Support       |
|	- 1.3 - Security Issues                |
|2) Configuring                                |
|3) Installing                                 |
|4) Using                                      |
|	- 4.0   - Invoking from a .shtml file  |
|	- 4.1   - Invoking from a .php file    |
|	- 4.1.2 - PHP SECURITY NOTE            |
|	- 4.2   - Using unicount-view.pl       |
|5) Trouble Shooting                           |
|6) Contact                                    |
|7) *** Special Thanks ***                     |
------------------------------------------------

________
1) About

  1.0 - General Information
  --------------------------
	UniCount is an SSI(Server Side Include) invoked webpage hit counter.It
	is extremely versatile in that it can act as a very customizable
	text counter or image counter.
	It 's features include detailed logging, PHP support,
	support for multiple webpages, and many more.
	UniCount is written in C. The reason I did not choose Perl to write this
	counter (Most are written in Perl) is the fact I wanted to challenge myself.
	Speed and CPU usage are the main advantages to using a binary CGI script as
	opposed to an interpreted one.
		I believe you will find this counter to replace any counter you are 
	currently using.  Please do not hesitate to send me feedback. All feedback,
	both positive and negative is read and appreciated. Thank you.
			

  1.1 - Multiple Document Support
  --------------------------------
	I just want to make it clear that you can invoke UniCount from more than 1
	document (Up to 4,096 documents to be exact). These documents can be either
	SHTML or PHP. UniCount stores a unique line for each document in the file
	you will specify when configuring. I have been extra careful to make sure
	the parsing routines are air-tight. (C was never meant for text parsing).
	If you find any bugs, please let me know!

  1.2 - Multiple Website Support
  ------------------------------
	You can also invoke UniCount with a QUERY_STRING if you are using the same
        unicount.cgi for multiple websites. Please see section 4.0.


  1.3 - Security Issues
  ---------------------
	The main (And only) security issue I can think of is the "must" of having
	the data and log files world-writable. Unfortunately, this is necessary for
	CGI applications of this nature. This issue poses the potential threat of
	a malicious user deliberately writing large amounts of data to these files,
	which could in turn fill the filesystem. The only obstacle would be the 
	kernel's limit on file space (usually 2 gigabytes). This is why it is very
	important that you keep these files hidden from all users. I recommend 
	using hidden filenames (filenames that begin with the '.' character) in 
	a directory that is not world-writable. You should also leave WANT_DEBUG
	commented out in conf.h if you are concerned with this issue.	

______________
2) Configuring
	
	Configuring UniCount is easy and painless.
	Simply edit the file include/conf.h. 
	I will not write about configuring UniCount in this file as conf.h is
	very explanatory.

_____________
3) Installing

	After you have edited include/conf.h to suit your needs, type:
	./Install.sh <destination>
	Destination should be the directory where you want the unicount.cgi
	binary to be installed.

________________________________
4) Using
  _________________________________
  4.0 - Invoking from a .shtml file
	
	To invoke UniCount from a server-parsed (shtml) document, insert the following
	line where you would like your counter displayed:
	<!--#include virtual="/path/to/unicount.cgi"-->
	e.g:
		<!--#include virtual="/cgi-bin/unicount.cgi"-->
	
	You will need to replace "/path/to/unicount.cgi" with the path you specified
	when you ran ./Install.sh.
	Please keep in mind it is not advised to use a path starting with "./"

	If you are using the same unicount.cgi for more than one website, you can
        invoke UniCount with a QUERY_STRING.
	e.g:
		<!--#include virtual="/cgi-bin/unicount.cgi?WEBSITE_1"--> or
		<!--#include virtual="/cgi-bin/unicount.cgi?BOBS_WEBSITE"-->
	UniCount will keep a tab for each one.
	
	NOTE: If you do not invoke UniCount with a QUERY_STRING, the website name
	will default to "UNICOUNT_DEFAULT".
	
  _______________________________
  4.1 - Invoking from a .php file

	To invoke UniCount from a php document:
	First, make sure you compiled UniCount with HAVE_PHP defined.
	Now, edit the file unicount-php. You will only need
	to edit the last line which says echo `/www/cgi-bin/unicount.cgi`;
	Change this path to the logical path where you installed unicount.cgi.
	You may now copy the file unicount-php into a directory accessable by 
	the php document that will call UniCount. From your php document, insert the
	following line where you would like UniCount to be displayed:

	<?php include("/path/to/unicount-php"); ?>

	You will obviously need to change "/path/to/unicount-php" with the 
	logical path to unicount-php.

	NOTE: If you are using a single php document as a template for your
	entire website (using include()), you should add the following lines 
	in unicount-php right after the first "$doc_uri =" line:

	$doc_uri .= getenv("QUERY_STRING");
	$doc_uri = EscapeShellCmd($doc_uri);	# For security

        -----------------------------
        MULTIPLE WEBSITE PHP SUPPORT:
      
        This feature is not yet supported.


  -------------------------------
  4.1.2 - PHP SECURITY NOTE

	Whenever you are working with a QUERY_STRING in PHP, you should
	ALWAYS parse the string of any potentially dangerous characters
	before doing anything else with it. Otherwise, users around the
	world may be able to execute arbitrary commands on your machine.
	This extra security measure is done with the EscapeShellCmd() 
        function.



  -------------------------------
  4.2 - Using unicount-view.pl

	unicount-view.pl is a CGI script written in Perl used to display
	the statistics of your UniCount log and data files in fancy HTML
	format. Before you copy this file into your cgi-bin, you need to
	open it with your favorite text editor and edit the first two 
	variables which point the logical paths of your counter and data
	files.  These paths should be the same as what you set them to
	in conf.h. Please make sure this file is chmod'd to 755 before
	you attempt to view it from your web browser.

_____________________
5) - Trouble Shooting

Problem:  "I did everything you said, but when I view my webpage, I see nothing,
	   and when I view the source - I see <!--#include virtual="....."-->"

Solution: Make sure the document containing that line has a ".shtml" extension.
	  If you are infact invoking this from a .shtml file, make sure the web-server
	  is setup to parse .shtml files. In Apache, this is done by uncommenting or adding the
	  following lines in httpd.conf:

	  	AddType text/html .shtml
	  	AddHandler server-parsed .shtml

	  Note:  If you are viewing the .shtml from your hard drive, the SSI directive
	  will not be parsed. It must be located in a directory recognized by the web
	  server, and must be viewed as a URL. (Not file://)


Problem:  "I did everything you said, but when I vew my webpage, I see:
	   [an error occured while processing this directive]"

Solution: Make sure you specified the correct path to unicount.cgi in the SSI directive.
	  If you know the path is correct, make sure that your webserver is setup to allow
	  the "include" SSI directive.


____________
6) - Contact

	If you have any questions/requests/additions/suggestions/compliments/critiquing, please
	send feedback to macabre@cfl.rr.com
	All feedback is greatly appreciated!

___________________
7) - Special Thanks

	I would like to thank the following people for their help in
	making UniCount grow:

	Andrew Brink (http://brink.linuxguru.net/)
	For his suggesting the logging routine.

	James and everyone at linuxguru.net for
	sponsoring and hosting the UniCount website. They're awesome!
	
	David Bandel for writing an article on UniCount in the July 2000
	issue of Linux Journal magazine.

	Robert Dalton (http://www.AccessWest.com/)
	For his support and testing pre-release versions of UniCount,
	and offering many helpful ideas such as multiple website support.

--------------------------------------------------------------------------------------------
Thank you for choosing UniCount! -Evil (macabre@cfl.rr.com)
