Visitor CGI


DESCRIPTION

The enclosed Visitor CGI script was written to allow website 
administrators to easily setup a visitors log for both pages they 
maintain, as well as their users.

After compiling and installing the CGI program, the website 
administrator only has to setup one small configuration file to allow 
all personal users to create their own visitors log.


DISCLAIMER

While I have attempted to test this program thoroughly, I make no claims 
that the program is 1) entirely safe from security attacks, or 2) 
without any errors.  If you want to use the program, please do so at 
your own risk.


COPYRIGHT

This program was developed and tested by Randy L. Pearson (rlp@intrlnk-
intl.com).  I hold the copyright, but will allow you to use the program 
under the shareware system.  If you like it and use it, please read the 
register.txt file for more information.

Please do not remove my copyright notice from the original source code, 
and please do not attempt to resell this product without my permission.


REQUIREMENTS

This CGI currently requires that the HTTP_REFERER environment variable 
be passed to CGI scripts from the HTTP Server.  See instructions later 
for how to test this.  If your HTTP Server does not do this, you will 
need a different HTTP Server or a different CGI script (Sorry!).

I have developed this program using the sample CGI code from the good 
folks at NCSA.  Thanks to them for all the hard work they have done in 
building and standardizing the Web.

The code was developed and testing on a Linux server running Spinner Web 
Server software.  Again thanks to Per and David (and numerous others) 
for all their hard work.



HOW DOES IT WORK?

Pretty simple actually.  When a new user adds their information, the 
data is POSTed to the visitor.cgi.  The CGI then locates the 
visitor.html page (more on this in a second) and using standard 
write/read commands, makes a copy of the page into a temporary file 
(default location is /tmp).

During the copy sequence, the CGI looks for the start of the visitor 
list.  This is identified by an HTML <table> tag.  Once this line is 
found, the new user info is inserted at the top of the list, and rest of 
the file is copied.  Then the new list is copied over the top of the old 
list.

Now what if you wish to make the list visually attractive to both web 
browsers that support table and those that do not?  You can append a 
<pre> tag to the <table> tag for these cases.  The lines the visitor.cgi 
file inserts have fixed length columns.  This lets older browsers 
display the lines as preformatted text, and all the name still line up 
neatly.  Luckily, most of these older browsers will ignore all the table 
codes.  The newer browsers ignore the <pre> tag and only process the 
<table> tag, so we get the best of both worlds. The CGI works with both 
table capable browsers as well as older ones.

As an added feature, this CGI also can scan the submitted text for 
profanity.  It will replace any desired word with a new word or phrase.  
See instructions later for how this works.



INSTRUCTIONS FOR ADMINISTRATORS

There is a makefile included with this archive.  You (or your website 
administrator) need to issue a make command to built the visitor.cgi 
program.  There is also an install option in the makefile, but the final 
directory may not be correct for your site.  Just copy the newly created 
visitor.cgi program into your cgi-bin directory and set it's permissions 
as required by your system.



MORE ABOUT LOCATING THE VISITOR LOG

Next, the website administrator must help the CGI script.  In order for 
the CGI to locate the exact visitor log that needs to be updated, it 
needs to map the URL to a real-world directory.


Here is an example:



http://www.intrlnk-intl.com/~randy/visitor.html


is stored in the real-world file named:


/home/randy/public_html/visitor.html



AND



http://www.intrlnk-intl.com/cats/visitor.htm


is stored in the real-world file named:


/home/http/cats/visitor.htm




The first example shows a user home page while the second is part of the 
main server space.  I have written the CGI to allow decoding both types 
of URLs.  This requires a short mapping file to be stored in the /cgi-
bin directory along with the CGI script itself.  The mapping file must 
be named 'visitor.map' and looks like this:



www.intrlnk-intl.com/~       /home/%u/public_html
www.intrlnk-intl.com:80/~    /home/%u/public_html
wolf.intrlnk-intl.com/~      /home/%u/public_html
wolf.intrlnk-intl.com:80/~   /home/%u/public_html
www.intrlnk-intl.com         /home/http
www.intrlnk-intl.com:80      /home/http
wolf.intrlnk-intl.com        /home/http
wolf.intrlnk-intl.com:80     /home/http


You must have one space or tab between the URL and the directory name.  
Additional spaces are ignored.

It is very IMPORTANT that you add all the possible names the client 
browser can refer to your site.  In the example above, my web server is 
named 'wolf', but also has a CNAME of 'www'.  Since the web server runs 
on TCP port 80, I need four different entries to cover all the possible 
combinations.  Some browsers always append the port number to the CNAME, 
while others convert the CNAME into the actual host name, and still 
others do both!  (Don't you love standards?)

You may wish to consider adding entries for the IP address itself, since 
this is a valid way to address the web site.

The CGI uses the HTTP_REFERER variable to search for the correct visitor 
log.  First, it removes the "http://" sequence.  Next, it looks for 
tilde (~) character.  If found, it will attempt to match the host name 
to one of the lines in the visitor.map file.  The %u is used as a 
placeholder, and will be replaced by the word following the tilde (~) in 
the URL.  This should be the user name.

If a tilde is not found in the URL, the CGI will then attempt to match 
the host and domain name (and possible port) to a real-world directory.

Finally, the CGI appends the directory name (if one exists) to the new 
path.  The CGI will then look for the visitors log in this directory.  
It can be named either visitor.html or visitor.htm.




INSTRUCTIONS FOR USERS/WEB SPINNERS


This CGI script is built in a way that requires three (3) separate HTML 
pages.  The first page holds the list of visitors, the second is used to 
display error messages, and the last is the form that allows users to 
add their name to the log.  It can be named anything you like, or could 
be incorporated into the main visitor log page itself.

There is also an optional file that can be used to filter out profanity 
or unwanted words.  A simple text file named "badword.lst" is scanned 
and loaded if found.  The format is described below.

Examples of each page are listed below along with some notes about using 
them.



VISITOR.HTML (or VISITOR.HTM)

This file is the web page that web surfers see.  It holds the names of 
the visitors to your home pages.


Example:

<html>
	<title>Randy L. Pearson's Visitors Log</title>
</html>
<body bgcolor=#C0D0E0>
<p>
<hr width=400 size=4>
<p>
<center><h1>Randy L. Pearson's Visitors Log</h1></center>
<p>
<hr width=400 size=4>
<br>
<center><a href=signup.html>Click here to add your name to the visitor's 
log</a></center>
<br>
<center><pre>
<table border=1>
<tr><td><b>Quanta Parker       </b> <td>Huntsville, Al.      <td>                                        
  <td><a href="mailto:quanta@intrlnk-intl.com">quanta@intrlnk-
intl.com</a>              <td> 1/05/96  9:47 pm</tr>
<tr><td><b>A.J. Albert         </b> <td>Huntsville, AL       <td><a 
href="http://www.intrlnk-intl.com/">http://www.intrlnk-intl.com/</a>            
  <td><a href="mailto:ajalbert@intrlnk-intl.com">ajalbert@intrlnk-
intl.com</a>            <td> 1/05/96 10:05 am</tr>
<tr><td><b>Randy Pearson       </b> <td>Ryland, AL           <td><a 
href="http://www.intrlnk-intl.com/~randy">http://www.intrlnk-
intl.com/~randy</a>      
  <td><a href="mailto:rlp@intrlnk-intl.com">rlp@intrlnk-intl.com</a>                 
<td> 1/05/96  8:21 am</tr>
<tr><td><b>Paul Ramseyer       </b> <td>Biloxi, MS           <td><a 
href="http://www.datasync.com/~ramseyer">http://www.datasync.com/~ramsey
er</a>       
  <td><a href="mailto:ramseyer@datasync.com">ramseyer@datasync.com</a>                
<td> 1/05/96  8:20 am</tr>
</table></pre>
</center>
<center>
Thanks for stopping by!
</center>
</body></html>


You can add features to the page as you like, but keep in mind that the 
CGI requires the <TABLE> tag to be on the first column of a line, 
followed by, or prepended by an optional <PRE> tag.  Do not remove the 
<TABLE> tag or the script will not work.  You can modify the table 
attributes if you desire (i.e. <TABLE BORDER=2>, etc).

Feel free to add background images, colors, sound, whatever you like.  
Remember, the <PRE> tag is used by older web browsers that do not yet 
support tables, while the <TABLE> tag is used by newer browsers.  Older 
browsers normally ignore the table codes like <TD> and <TR>.



ERROR.HTML

If the visitor log CGI encounters any errors while attempting to add a 
visitor to the log, it will use this page to display an error message.


Example:

<HTML>
<HEADER>
  <TITLE>Randy's Visitor Log CGI Error</TITLE>
</HEADER>
<BODY BGCOLOR=#E07070>
<CENTER><H1>Visitor Log CGI Error</H1></CENTER>
<HR>
An error occurred while trying to add your information to the visitors 
log.
Read the message below and attempt to correct your entry.
<P>
If you do not understand the message, or it appears to be a genuine 
error,
please send an e-mail message with the error message to
<A HREF="mailto:rlp@intrlnk-intl.com">rlp@intrlnk-intl.com</A>. I will
attempt to resolve the problem.
<HR>
<P><B><I>
CGI ERROR HERE
<P>
</B></I>
<HR>
<CENTER>Thank you for understanding...</CENTER>
</BODY>
</HTML>


Again, you can modify the page as needed, but the line that reads "CGI 
ERROR HERE" must remain.  The script will replace that line with a 
description of the error that occurred.

If you want to test the error page, temporarily rename the visitor.html 
file and then run the signup form.  The CGI will report a "file not 
found" error.  You can also submit a signup request without filling out 
any fields to display an error.



SIGNUP.HTML

This file contains the form that users fill out to add themselves to 
your visitors log.  You could incorporate the form into the VISITOR.HTML 
if desired.


Example:

<html>
<header>
<title>Visitors Log Signup Form</title>
</header>
<body bgcolor=#C0D0E0>
<center>
<hr width=580 size=10>
<h1>Sign the Visitor's Log</h1>
<hr width=580 size=10>
Please fill out the information requested below, then click on the OK 
button at the bottom.
</center>
<form method=post action=/cgi-bin/visitor.cgi>
<pre>
          Name: <input type="text" name="name"   size=30>
          City: <input type="text" name="city"   size=30>
         State: <input type="text" name="state"  size=2>
        E-Mail: <input type="text" name="email"  size=30> (optional)
           URL: <input type="text" name="url"    size=30> (optional)
           
           <input type="submit" name="send" value="  OK  ">  <input 
type="reset" name="clear" value="Clear">
</pre>
</form>
</body></html>


Again, feel free to enhance the page to match your style.  You can 
rename the form if desired, but remember to update the link in the 
VISITOR.HTML file with the new name.  The field names MUST remain as 
displayed above.



BADWORD.LST

This file is simply a text file that has the unwanted phrase or word and 
the replacement text separated by a semi-colon.  (I may enhance this 
later to allow the user to configure some additional parameters.)


Example:

 gotohell: go where it's warm
 go to hell: go where it's warm
 goto hell: go where it's warm
 go tohell: go where it's warm
 you suck: play nice
 this sucks: this is great
 ass: you sit on this
damn: something that stops water
damm: something that stops water


The spaces in front of the words are important, it help to prevent 
replacing words like: 'sassy' with something like 'syou it on thisy'.  
You can add as many words or phrases to the file as you can think of.  
Any line that does not have a colon (:) or that starts with a pound (#) 
symbol is ignored.

Case is ignored when actually performing the replacements.  For example, 
look at the following phrase replacements:


ORIGINAL TEXT              REPLACED TEXT

You just GO TO HELL!  -->  You just go where it's warm!
You just go to hell!  -->  You just go where it's warm!



FINAL NOTES -

The VISITOR.HTML, SIGNUP.HTML, ERROR.HTML and badword.lst must all 
reside in the same directory.  They can be all upper-case or all lower-
case, and can end in either '.html' or '.htm'.

Please read the entire documentation before you attempt to contact me, 
but feel free to do so if you think of an enhancement or find a serious 
problem.  You can reach me via e-mail at:

rlp@intrlnk-intl.com


Randy L. Pearson
01/09/96