VisitorBook Pro!

 

• Introduction  
• Pre-install decisions
• Editing the files
• Uploading the files
• Setting permissions
• Testing the setup
  

Introduction

Welcome 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 installation process.

Note: For the latest documentation, updates, add-ons, and all other VBPro information, go to www.visitorbook.com.

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

CGI Location
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.

/usr/local/apache/vbfiles
	/books
	/vbtemplates
		/Standard_Guestbook
	cgi-lib.pl
	masteradmin.pass
	vb.shared.lib.pl
	
/usr/local/apache/cgi-bin/vbpro
	vb.config.pl
	vbadmin.cgi
	vbmasteradmin.cgi

Installing VBPro: Editing the files

For the 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 function.

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 got

Some settings for the path to Perl are:

#!/usr/bin/perl
#!/usr/local/bin/perl
#!/bin/perl
#!/usr/sbin/perl

After you 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 be different):

$configfile = "vb.config.pl";

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

$templatedir = "/usr/local/apache/vbtemplates";
This is 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.)

$sharedlib = "/usr/local/apache/vbfiles/vb.shared.lib.pl";
Path to 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.

$cgilib = "/usr/local/apache/vhosts/hoho/vbfiles/cgi-lib.pl";
This is 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.

$cgi_url = "http://domain.xyz/cgi-bin/vbpro/vbpro.cgi";
This should 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.)

$masterpass = "/usr/local/apache/vbfiles/masteradmin.pass";
This is the path of the password file for the master administrator. A default version of this file was included in the VBPro distribution.

$mailprog = "/usr/sbin/sendmail";
This is 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).

$basebookdir = "/usr/local/apache/vbfiles/books";
This is 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.

$root_livedir = "/usr/local/apache/htdocs/books";
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.

$root_liveurl = "http://domain.xyz/books";
This URL corresponds with the directory above. Be certain not to include a trailing slash (do not end this url with a /).

$picture_url = "http://web.hoho.com/vbpro/pics";
The administrator 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 directory here.

$logouturl = "http://domain.xyz";
After the 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.

File list
Set the following files according to the permissions in brackets.

/usr/local/apache/vbfiles [755]
/books [777]
/vbtemplates [755]
/Standard_Guestbook
cgi-lib.pl [755]
masteradmin.pass [777]
vb.shared.lib.pl [755]

/usr/local/apache/cgi-bin/vbpro
vb.config.pl [755]
vbadmin.cgi [755]
vbmasteradmin.cgi [755]

How to 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).

chmod 777 /path/to/file_or_directory

There are two ways to set the permissions using an FTP client, depending on your computer platform.

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.

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

1. 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.
   
   
2. 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?
   
   
3. Did you use the correct path to perl in the scripts?
   
   
4. 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.
   
   
5. 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 problem.
   
   
6. 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 directory.
   
   
7. Check all user-configured options. Are you sure they are correct? Would your system admin be of help to verify?