COPYRIGHT

Guestbook
Copyright 2001 London Perl Mongers, All rights reserved

LICENSE

This script is free software; you are free to redistibute it
and/or modify it under the same terms as Perl itself.

URL

The most up to date version of this script is available from the nms
Scripts Archive at  <http://nms-cgi.sourceforge.net/>

SUMMARY

The Guestbook is a program that allows visitors to your website to leave
a message on the Guestbook page.

FILES

In this distribution you will find five files:

README         - This file. Instructions on how to install and use guestbook
guestbook.pl   - The main Perl program file.
guestbook.html - The file in which the guestbook entries are saved.
addguest.html  - The form that visitors will use for a guestbook entry.
guestlog.html  - A log file of those who have added entries to guestbook.


CONFIGURATION

In order for this program to work properly on your webserver it will require
a small amount of configuration before you upload it.

All of the configuration is done by editing the program file directly, you
can do this in your favourite text editor or notepad if you are on Windows.
You probably don't want to use a wordprocessor to do this unless you are
certain you can save the file as plain text.

Firstly you will need to change the first line of the program:

   #!/usr/bin/perl -wT

so that it points at the proper location of perl on your webserver - your
system administrator or webhosting provider should be able to tell you this.
You only need to change the '/usr/bin/perl' part - all of the rest of the
line must be left exactly as it is.

There are a number of variables that you should change in guestbook.pl which
alter the way that the program works.

If you are unsure of the appropriate value for variables that relate to the
setup of your webserver you should ask your system administrator or
web hosting provider.

$DEBUGGING     - This should be set to 1 whilst you are installing
                 and testing the script. Once the script is live you
                 should change it to 0. When set to 1, errors will
                 be output to the browser. This is a security risk and
                 should not be used when the script is live.

$guestbookurl  - The public URL of your guestbook.html file.

$guestbookreal - The filesystem location of your guestbook.html file on the
                 webserver.

$guestlog      - The filesystem location of your guestlog.html file on the
                 webserver.

$cgiurl        - The public URL of the guestbook.pl file.

$style         - The URL of a CSS stylesheet that will be used for the
                 HTML that is generated by the program.

$mail          - If this is set to 1 then you will be notified by e-mail
                 of any new entries.  If it is set then the next two
                 variables must be set correctly.  If you don't want to
                 receive e-mail then set this to 0.

$recipient     - The e-mail address of the person who wants to receive
                 notification of new guestbook entries.
                
$mailprog      - The full path to the program that will be used to send
                 e-mail - this should also include any command line
                 options that might be required.

$uselog        - If this variable is set to 1 then all new entries to the
                 guestbook will be recorded in a short log, also any
                 errors will be recorded.  If you don't want this
                 facility then set this to 0.

$linkmail      - If this is set to 1 then the e-mail addresses that 
                 visitors enter will be added as mailto: links rather than
                 just as plain text.  You may not want to do this if you
                 are concerned that spammers might harvest the addresses.

$separator     - This determines how the entries in the guestbook page are
                 separated.  If it is set to 1 then the entries will be
                 separated by a horizontal rule (<hr />).  If it is set
                 to 0 then they will be placed in separate paragraphs.

$redirection   - If this variable is set to 1 then the program will issue
                 a browser redirection to the guestbook page after the entry
                 has been added. If it is set to 0 then the visitor will be
                 presented with a page with a link to the modified guestbook
                 page.

$entry_order   - If this is set to 1 then new entries will be added to the
                 top of the guestbook page, if it is set to 0 they will be
                 added at the end.

$remote_mail   - When this is set to 1 then the visitor who makes the
                 guestbook entry will be sent a confirmation e-mail 
                 ( assuming they have entered a valid address ) - you
                 will need to have set $mailprog and $recipient as described
                 above.  You should think carefully about setting this
                 variable as it would be simple for someone to turn your
                 guestbook into an anonymous mail-bomb if they were to
                 enter someone elses e-mail address and repeatedly submit
                 the form.

$allow_html    - If this is set to 0 then all HTML will be stripped from
                 the visitor comments before being added to the guestbook
                 page.  If it is set to 1 then a relatively safe set of
                 HTML elements will be allowed in the input - please see
                 the code in guestbook.pl to find which tags are allowed.
                 Previous versions of this program allowed a user to enter
                 any HTML they wanted which allowed the possibility of
                 third party scripting attacks or defacement of the page.

$line_breaks  -  When set to 1 all of the carriage returns in the visitors
                 comments will be changed to <br /> - this is probably not
                 necessary if $allow_html is set to 1.


You will need also to edit the addguest.html file so that the line :

   <form method="post" action="http://your.host.com/cgi-bin/guestbook.pl">

has the action attribute pointing to the URL of your guestbook program.

You might also want to edit this and the guestbook.html so that it matches
the appearance of your website - being careful that you don't remove the
'<!--begin-->' comment that the program uses to know where to enter the
new entries.

INSTALLATION

All that is need to install the Guestbook is to copy the guestbook.pl file
to the cgi-bin directory (or whatever is appropriate for your system - you
should ask your system administrator or web hosting provider about this if
you are unsure ) on your web server and to copy the addguest.html, 
guestbook.html and guestlog.html to the location that you will have entered
in the configuration above.

On some systems you may need to rename guestbook.pl to guestbook.cgi
(or some other extension that the web server uses to indicate a CGI
program.) Again, your system administrator will know if this is the case.

You will probably need to turn on execute permissions to the file. You can
do this by running the command "chmod +x guestbook.pl" from your command
line. If you don't have command line access to your web server then there
will probably be an equivalent function in your file transfer program.

SUPPORT

For support of this script please email:

  <nms-cgi-support@lists.sourceforge.net>

This mailling list is read by the NMS developers and other helpful people
who will try to help you solve your problem.

