to VisitorBook Pro and congratulations on owning the best guestbook
system around! At Command-O Software, we're confident that VisitorBook
Pro is the best guestbook software around: it's packed with features,
has a cool but useful interface, and is supported by a great manual
and staff, should you need us!
By now, you've expanded the VBPro files and may have already started
tinkering with it a bit. This manual will take you through the entire
process of running a VBPro system: from getting it running to creating
and maintaining new books.
From here, continue to the next section of this chapter, beginning the
Note: For the latest documentation, updates, add-ons, and all other
VBPro information, go to www.visitorbook.com.
VBPro: Pre-install decisions
Before you begin the main tasks involved in setting up a VBPro system,
you should determine a few things that will help make the other tasks
easier to understand and complete.
Before you upload any of the VBPro components, you will need to have
and idea of where to place them. VBPro consists of several CGI scripts
that need to be in a directory on your web server that is capable of
executing CGI scripts. Most often, your service provider will point
you to the "cgi-bin" directory. This will often be the best
place to store the CGI scripts. However, if you have the ability, you
may wish to create a directory inside cgi-bin, called parhaps "vbpro",
which will store the CGI scripts. In this manner, you can keep the files
together and organized in a directory inside cgi-bin.
Data File Location
You will also need to determine where you want to store the datafiles
for the VBPro system (book entry information, system access records,
and so on). The VBPro system will look for all the data files in this
one directory; therefore, it is crucial that this directory is in a
safe place. For example, it would not be a good idea to create a data
directory that is accessible on the web. If at all possible, you will
want to create a directory for data that is NOT accessible from a web
browser -- in other words, it should reside outside of your main HTML
or htdocs directory.
General Setup Tree
For the setup of the VBPro system, it is a good idea to have a feel
to the structure, or tree, of the VBPro setup. Below, a simple text
diagram shows one possible setup. Thinking out this stage for your own
server will help you when you configure the setup files and will also
speed the process of uploading files.
VBPro: Editing the files
VBPro system to function properly, several configuration options must
be set based on your system layout and personal preferences. Though
getting this step right may take a bit more time depending on your experience
and knowledge, it is the most crucial step in getting the system to
Editing the CGI files
VBPro consists of several scripts that perform ceratin funtions. Most
of the scripts need the same set configuration information, and all
of this information is stored in one configuration file. As a result,
relatively little has to be done to each individual script.
First, you must modify each of the three CGIs (vbpro, vbadmin, vbmasteradmin)
to point to the Perl program on your system. This means the first line
of each of the programs must contain a pound sign, an exclamation point,
and the full path to the perl program. If you do not know what should
go here, there are a few ways to find out:
- Ask your ISP/Service Provider what the correct path to Perl is
- In Telnet, type 'which perl' or 'whereis perl'
- On your ISP, snoop around in someone else's CGI and see what they've
Some settings for the path to Perl are:
have the correct path to Perl set, the only other thing that must be
modified in each program is the configuration file information. The
program needs to know where to look for the configuration file that
stores all the other information you will input. Decide now (if you
haven't already done so) where you are going to place this file. (See
Section I, Chapter 2 if you need help deciding where things go.)
To change this variable, simply modify the location that is already
inside the quotes. Be sure to leave the double quotes in place. For
example, your configuration will look similar to this (the path will
the configuration files
Once your VBPro system is working, almost every aspect of maintaining
several guestbooks and users is easily managed thanks to VBPro's comprehensive
web-based administrator tools. However, in order for these tools to
function properly, the main configuration file must be configured correctly.
Therefore, it is reccomended that you understand what each option in
the configuration file does as you go along editing it. This section
steps you through each variable in the vb.config.pl file.
the path of the directory where VBPro template files are stored. These
files are used only in the master admin program. Nevertheless, they
are crucial; if no templates are installed, new books can only be created
using the custom book process (powerful, yet more time consuming.)
the Command-O VBPro shared library. This file contains VBPro code that
is used by most of the three programs. Putting it all in one file saves
space since the code in it isn't written several times among the three
CGIs. Like all of the VBPro files, this should be located in a safe
place on your server.
the path of the CGI-LIB library. Written by Steve Brenner, CGI-LIB is
a popular file containing many functions that making processing forms,
among other things, easier for developers such as Command-O Software.
This file is required.
be the URL of the "vbpro" CGI (by default, it is named vbpro.cgi).
This value is used by the Master Admin program when making new books.
Particularly, it will automatically place this value in templates that
ask for it. (All Command-O templates use this technique.)
the path of the password file for the master administrator. A default
version of this file was included in the VBPro distribution.
the location of your mail program on your server (this is usually called
sendmail). If you want to find this and have a shell account, login
and type "which sendmail" (no quotes).
the path of the directory where books will be created. This may be something
like /usr/local/etc/httpd/vbpro/books . Information about guestbooks
will be stored in this directory. BE CAREFUL -- don't end this value
with a forward slash (/)! Follow the example above.
When a new
book is created using the the master admin program, this is the absolute
top place where the book HTML files will be allowed to be created. This
should probably be set to a designated "books" directory inside
your main htdocs directory for easiest maintainence and security. However,
if you set this to simply your htdocs directory -- or worse, nothing
at all -- whoever uses the master admin program (which should be just
you or very few people) can create books anywhere inside that directory.
This is not a huge risk since only at most few responsible people other
than yourself should have access to the master admin program. Nevertheless,
the stricter, the better.
corresponds with the directory above. Be certain not to include a trailing
slash (do not end this url with a /).
programs use a few graphics in their interfaces. Upload the images that
came with the software somewhere on your web site and point to that
user admin or master admin logs out, the CGI will redirect them to this
page. Not very important, as long as you have something.
Installing VBPro: Uploading the files
Provided you completed Step 2 and thought about where your files should
go, this next step should be easy. Following the structure provided
as an example in Step 2 (or using your own choices), upload the corresponding
files and create the necessary directories on your server.
Except for included images, all of the VBPro related files are text
files. Therefore, if you have an option, upload all of the files (except
images) in text mode (as opposed to binary). Usually FTP programs these
days have an "Auto" default setting and are smart enough to
upload the files the correct way without any tinkering.
Installing VBPro: Setting permissions
Setting the permissions of your folders and files is another crucial
step in starting you VBPro system. Your UNIX-based host relies on a
system of permissions in order to control what users on your system
can access and run specific files and programs. While it is not necessary
(in our estimation) to describe the typical permissions system in its
entirety and in detail, we will explain what you need to know to understand
how to set the VBPro permissions correctly.
When you or anyone visiting your web site uses one of the VBPro CGI
scripts, the web server runs the script and attempts the desired task
(such as adding an entry to a guest book. In most setups, you will need
to change the settings on files and folders on your server -- which
are called permissions -- in order to allow the web server to view and
edit text files, create and view directories, and execute scripts (the
three main programs).
So what permissions exactly does the web server need? Well, for many
of the text files, the web server needs to be able to view and edit
them. For most directories, the web server needs the permissions to
list the contents and create new files in it. For all of the scripts,
the web server needs to be able to execute them.
Looking at each file, we could tell you exactly what permissions are
needed and what are not necessary. However, doing this would take you
much more time to set up, and would not be guarateed to work uniformly
across all servers that run VBPro. So, we will tell you some groups
of files and what permissions to assign them; if you wish to be more
specific in setting permissions so as to enhance the security of your
setup, we encourage you to experiment with your setup and/or contact
your server admin. Basically, if you are on a shared system, some of
the files below could potentially be accessed and/or modified by a knowledgable
user (specifically, files where the last number of the permission mode
is 7). Again, we encourage you to learn more about permissions from
your service provider and how they apply to your on your setup.
Set the following files according to the permissions in brackets.
set the permissions
To set the permissions for the files using a telnet/shell account, follow
the example below. Type the following command in to the telnet window
for each file (be sure to change the permission mode/numbers as necessary).
two ways to set the permissions using an FTP client, depending on your
On a Macintosh, we use Fetch 3.0. Find the file you want to change,
and click once on it. Go to the "Directory" menu, and select
"Set Permissions..." Select all of the boxes for 777, and
click OK. For 755 files, click all of the boxes in the first column,
the top box only in the middle column, and all of the boxes in the last
column. Repeat this process for all files and directories as needed.
On a Windows machine, a popular way to do it is using WS FTP. Go to
the directory that contains the file you want. Right click with your
mouse, and select "Site" from the window that pops up. Then,
type "chmod 777 books" (or whatever the mode/file is). Repeat
this process for all the files and directories as needed.
VBPro: Testing the setup
If all went well in the last five chapters, then your VBPro setup should
be ready for prime time. The first way to test this is to log in to
the masteradmin CGI.
First, locate the masterlogin.html file. If you haven't already done
so, modify the HTML form in this file to point to the masteradmin.cgi
script on your server. Then, upload the form to your server and log
in with the user id "admin" and default password "admin".
If all goes well, you will be presented with the main admin screen.
However, this first test will probably not fail. We're not saying that
our programs or documentation lead you in to building a flawed setup;
rather, from our experience in distributing and supporting CGIs over
many many years, we have seen that typically new users have trouble
setting up programs for the first time. Additionally, you could have
configured the programs with invalid information about your server.
Follow this troubleshooting checklist when things don't work.
- Are you getting a server error (something like
"Internal Server Error") or a VBPro error (the error page
begins with "VBPro: Error")? If it is a VBPro error, then
you know the CGI executes and your setup (permissions or configuration
file) is flawed somewhere. If, however, you get a server error, continue
following the checklist to pinpoint the problem.
- Check your web server's error log. Can you glean
any useful information for the error message? Can you ask your system
admin what it might mean?
- Did you use the correct path to perl in the
- Did you upload the files in ASCII mode? Try
viewing a script in your FTP ot telnet program. Does it look okay?
Do you see strange characters or is the file all on one line? If so,
you need to re-upload the file in text mode and in such a manner that
your FTP program will translate it correctly. Experiment.
- Rethink your permissions. Try setting every
file and folder related to VBPro to 777. See if it works, then set
the permissions back (because leaving files accessible like this is
not a good idea from a security standpoint). If doing this worked,
then play around with the permissions until you find the setup works.
Ask your ISP for help if you have resolved it to be a permissions
- Check the file name. Do the scripts end with
.pl or rather do they end with .cgi? Though either should work, your
server may be finnecky or configured to only support one in a particular
- Check all user-configured options. Are you sure
they are correct? Would your system admin be of help to verify?