GUIDE - Guestbbok

How do I set up a guestbook on my Web site?

In order to have a properly working guestbook, you must follow the setup procedure carefully. The procedure described here differs slightly from procedures offered before, so it is important to read closely.

There are actually four parts to the guestbook:

guestbook.pl

This is the CGI script that you will need to copy and modify.

guestbook.html

This is the HTML file that actually contains the guestbook as it is shown to visitors. This file is modified by the guestbook.pl script.

addguest.html

This is the page that visitors will use to add their entry to your guestbook.

guestlog.html

This is a simple log of events and errors, generated by the guestbook.pl script. It is really only for your own information; you don't need to make it visible to visitors.

Before you begin, decide where you want guestbook.html and addguest.html to live in your Web site. You will normally want to place guestbook.pl in a CGI directory, although this is not strictly required (because it has the .pl extension, it will execute as CGI from any directory).

To begin, the script must be copied to your own Web directory. It cannot be run from the system CGI directory because customization is required. To copy the script, use one of these sequences of commands via Telnet, as described in the FAQ on CGI.

For Advanced accounts:

cd ~/public_html
mkdir cgi-local
cp /usr/www/cgi-bin/guestbook.pl cgi-local
chmod 755 cgi-local/guestbook.pl

For Webmaster accounts:

cd ~/public_html
cp /usr/www/cgi-bin/guestbook.pl cgi-bin
chmod 755 cgi-bin/guestbook.pl

Next, use your favorite editor to modify the script. You will need to set four variables within the script itself:

$guestbookurl

This is the full URL of your guestbook file, normally called guestbook.html. This file should not be placed in your cgi-bin directory! Examples:

$guestbookurl = "http://www.domain.com/guestbook.html";

Don't worry about the contents of the guestbook.html file just yet.

$guestbookreal

This is the "real" path to guestbook.html on the server. This is not a URL. Your Web site is stored under either /usr/www/users/username/ or /u2/www/users/username/; you can find your path with this command sequence (via Telnet):

cd ~/public_html
pwd

Examples:

$guestbookreal = "/usr/www/users/username/guestbook.html";

...or:

$guestbookreal = "/u2/www/users/username/guestbook.html";

$guestlog

This is the "real" path to the guestlog.html file. This follows the same rules as $guestbookreal. Examples:

$guestlog = "/usr/www/users/username/guestlog.html";

...or:

$guestlog = "/u2/www/users/username/guestlog.html";

$cgiurl

This is the full URL to your copy of the guestbook.pl script. Examples:

$cgiurl = "http://www.domain.com/cgi-bin/guestbook.pl";

...or:

$cgiurl = "http://www.domain.com/cgi-local/guestbook.pl";

...or:

$cgiurl = "http://www.pair.com/username/cgi-bin/guestbook.pl";

If you choose to use cgiwrap to run your guestbook, the correct setting for $cgiurl is:

$cgiurl = "http://www.domain.com/cgi-sys/cgiwrap/username/guestbook.pl";

The guestbook.pl script can be further configured with a wide variety of options, set as 1 ("yes") or 0 ("no") inside the script itself:

$mail

If set to 1, you will be sent an e-mail message whenever a new entry is made in the guestbook. If this is set, you must specify a value for $recipient.

$remote_mail

If set to 1, the submitter of any new entry will be sent a standard e-mail message as acknowledgment. If this is set, you must specify a value for $recipient.

$recipient

If $mail or $remote_mail is set to 1, this field is required. It specifies your own e-mail address.

$uselog

This specifies whether or not the logging feature will be used.

$linkmail

If set to 1, e-mail addresses in guestbook entries will be shown as active mailto: hyperlinks.

$separator

If set to 1 (default), <HR> is used as the separator between guestbook entries. If set to 0, <P> is used instead.

$redirection

If set to 1, the user will be automatically redirected back to the guestbook. This works with most browsers.

$entry_order

If set to 1 (default), the newest entries will appear at the top of the guestbook. If set to 0, the newest entries will appear at the bottom.

$allow_html

If set to 1 (default), HTML tags are allowed within guestbook entries; if set to 0, HTML tags are filtered out.

$line_breaks

If set to 1 (not the default), line breaks in the comment field are retained as <BR> tags in the guestbook entry.

When you have finished configuring the guestbook.pl script, the rest is fairly easy. Prototypes for the remaining three files (guestbook.html, addguest.html, and guestlog.html) can be found in /usr/local/pair/guestbook/ on the servers. You will need to copy these files to the location(s) you selected in your Web site, and set permissions for the guestbook.html and guestlog.html files as follows:

chmod 666 guestbook.html guestlog.html

Finally, edit the guestbook.html and addguest.html files. You will need to specify the correct URL for addguest.html inside guestbook.html, if they are in different directories for some reason. You will also need to specify the correct link to your home page, or remove that portion of guestbook.html entirely. You will need to specify two URLs within addguest.html - the URL to the CGI script should be placed in the ACTION field of the FORM tag, and the URL of the guestbook itself should be fixed at the bottom of the file.

You can further customize the guestbook.html and addguest.html files in any manner you like. The only restriction is that the <!--begin--> tag must be present in the guestbook.html file; it indicates where new entries should be added.

If you are concerned that other users on the system could tamper with your guestbook entries (because the guestbook.html file is world-writable), you can use cgiwrap on your guestbook.pl script. The correct FORM tag in addguest.html then becomes:

<FORM METHOD="POST" ACTION="/cgi-sys/cgiwrap/username/guestbook.pl">

...and you must change $cgiurl in guestbook.pl to:

$cgiurl = "http://www.domain.com/cgi-sys/cgiwrap/username/guestbook.pl";

You can then protect your guestbook with:

chmod 644 guestbook.html guestlog.html