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 system command that the script should invoke to
                 send an outgoing email. This should be the full path
                 to a program that will read a message from STDIN and
                 determine the list of message recipients from the
                 message headers. Any switches that the program
                 requires should be provided here.

                 A $mailprog setting that works for many UNIX-like
                 hosts is:

                   $mailprog = '/usr/lib/sendmail -oi -t -oem';

                 Some other UNIX-like hosts need:

                   $mailprog = '/usr/sbin/sendmail -oi -t -oem';

                 If your web server lacks a sendmail binary, you can
                 use an SMTP relay instead, by setting $mailprog like
                 this:

                   $mailprog = 'SMTP:mailhost.your.domain';

                 You will need to replace mailhost.your.domain with
                 the name or IP address of an SMTP server configured
                 to relay mail for the web server.

                 Your system administrator or hosting provider should
                 be able to tell you either the path to sendmail on the
                 web server or the name of a host that will act as an
                 SMTP relay for the web server.

$postmaster    - The envelope sender address to use for all emails
                 sent by the script.  This address will recieve bounce
                 messages if any of the emails cannot be delivered.  If
                 in doubt, put your own email address here.

$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.

$linkname      - If this is set to 1 then the home page URL that visitors
                 enter will be used to make the "name" field into a link.

$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.

$timezone     -   If set this will over-ride the timezone as set on the
                  server.  The timezone is a three upper case letter code
                  with an optional offset from UTC (The time in London) and
                  a code for daylight saving time.  Some examples might be:

                       AST4ADT   America/Thule
                       CST6CDT   America/Chicago
                       EST5EDT   America/New_York
                       MST7MDT   America/Denver
                       PST8PDT   America/Los_Angeles
                       YST9YDT   America/Anchorage
                       ROC       Asia/Taipei
                       ROK       Asia/Seoul
                       NZ        Pacific/Auckland
                       MET       Europe/Paris

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.

