Example: Downloading and Installing a Guestbook Script
Let's take a look at the steps required to download and install a typical CGI script on a server. For this example, I'm going to use the Guestbook script from the NMS collection of scripts. The guestbook program allows users who visit your site to enter some personal information that will be published as part of your site's guestbook. Other users who visit your site can view the guestbook and add entries of their own. One nice thing about the NMS scripts is that they're designed to allow users to get them up and running quickly. The documentation is clear and concise, and the scripts themselves are written so that they're easy to configure for the local computer. The guestbook script is available at:
The script and its attending files can be downloaded in any number of formats; you should download it in the format that's appropriate for your platform. After you've downloaded it, you should unpack the archive into a directory outside your Web directories. The package comes with a CGI program (guestbook.pl), several HTML documents, and a README file which explains how to install the application.
By unpack, I mean that you should use the appropriate application to extract the files from the archive. On Windows, you might use WinZip to extract the files. Under UNIX, you would most likely use gzip and tar.
Configuring the Script
After you've downloaded and unpacked the script, the next step is to get the guestbook up and running on your Web server. The first step is to read the README fileit explains exactly what you need to change to get the script to work. Because it's a Perl script, you'll have to edit it so that it works in your environment. Generally, that means editing the shebang line (the first line of the script), so that the pointer to the Perl interpreter is correct. For example, the script is set by default to look for the Perl interpreter at /usr/bin/perl. On my Web server, Perl is installed at /usr/local/bin/perl, so I changed the first line to point to the correct location. After that's done, the script should run, but there's still more work to do.
The first line of a UNIX script, the one with the pointer to the script interpreter is called the "shebang line." It's called that because the first two characters are #!. The # is sometimes called the hash character, and UNIX people call exclamation points bangs, thus shebang.
To get the script working, you have to go into the script and set some variables so they reflect your environment. These variable assignments are found in the guestbook.pl script immediately after the comments at the top. Some of the information you must enter or verify is the location of the date program on your system, the URL where the guestbook form is located, and the name of the file to be used as the guestbook log. There are also a number of options that can be set to alter the behavior of the script. These options are described in the README file.
Installing the Files and Setting Permissions
You must put all the files in the proper locations. The guestbook.pl file should reside in your cgi-bin directory, and the HTML files distributed as part of the guestbook application should reside under the document root on your Web server with the rest of your static HTML documents. Some of the variables in guestbook.pl will have to be set after you've determined the final locations for the files in the package. You also have to edit the addguest.html form and change the action attribute of the form tag so that it points to the location where you installed guestbook.pl.
You also have to make sure that the actual guestbook file, guestbook.html, and the guest log, guestlog.html, have the proper permissions set. They must be writable by the user that the Web server runs as. You can either change the owner of the files to the Web server user (often nobody), or just make the files world writable. It's up to you.
If you're a Windows user (especially one who's running the Web server as yourself), you don't need to worry about this. All of the scripts will be able to write to the data files already.
These concepts are universal to all CGI scripts that write to local files, so I'll elaborate some. Under UNIX and Windows, all processes run as a particular user. For example, if I log into a computer running UNIX and start a Web browser, the Web browser process will run under my user ID. When the Web server is started, the process runs under the user ID that started it, or under the user ID that's assigned to the process. For security purposes, the Web server processes are often assigned to the user ID nobody, which has few, if any, privileges. To change the owner of the guestbook and log file to the user ID nobody, the following commands are used:
chown nobody guestbook.html guestlog.html
If you opt not to deal with changing the owner of these files, you can just give all the users on the server write access to them. The big problem here is that if the computer on which the guestbook runs is used by multiple users, they'll all have the ability to modify that file. If you're worried about that, you should change the owner to the Web server user. If that's not a concern, you can just use the chmod command to provide write access to the files to all users on the system. The following command is used:
chmod o+w guestbook.html guestlog.html
Testing the Script
After you're done with the installation, you should be able to run the script. If it isn't working, read over the documentation again to make sure that you've set everything up properly. Then, if it still won't work, check out the next section of the hour to find out how to debug your CGI scripts. When the script is working, the guestbook will appear in your browser as it does in Figure 3.1.
Figure 3.1 The guestbook from the NMS project.
Customizing the Look and Feel
After you have the script working, you can edit all of the files associated with the guestbook to align them with the look-and-feel of your Web site. There are some instructions on customizing the files associated with the guestbook in the documentation. To view the guestbook on my Web site, use the following URL:
In Figure 3.2, you can see the addguest.html script after its appearance has been changed to fit the design of my Web site.
Figure 3.2 A customized version of the addguest.html file.