Procedure for adding a Guestbook to your Web Site

This page presents the procedure for adding a Guestbook script to your Web site. For installing other CGI scripts, refer to the General CGI procedure.

1. Download the guest book script: Go to Matt's Script Archive http://www.worldwidemart.com/scripts/. Go to the Guestbook section.

    

2. Download the zipped (.zip) file for Windows / Macintosh.

    

3. Unzip the file. You may need a program such as WinZip, PkZip or Stuffit Expander to open it.

   It contains the following files:
   1. guestbook.pl
   2. guestbook.html
   3. addguest.html
   4. guestlog.html
   5. readme file

   The .html and .htm files are Web pages. The .pl files and .cgi files are the CGI script files. The README file is a text document containing directions.

   NOTE: You may not always see the filename suffix or extention such as ".pl" or ".html" when looking at the files in Windows. To tell Windows to show the suffixes, do the following: Run the Windows Explorer program, "Start" -> "Programs" -> "Windows Explorer" Select "Tools" -> "Folder Options..." Click the "View" tab at the top of the window that appears Under "Advanced settings:", uncheck "Hide extentions for known file types", then press "OK"

    

4. Read over all the documentation for the script in the README file. This tells you where you will have to upload the files and what changes you will have to make in the code of the script. In the case of this guestbook script, we have spelled out all the changes you will need to make to install it on Penn State's Personal Web server. Reading and understanding the documentation is really the most important step to installing a script.

    

5. Open the guestbook.pl file. You will need to open the file in a text editor. See the table below for examples. We recommend WordPad for Windows users, TextEdit for Mac OS X and BBEdit (if available) for Mac Classic.

   The location of the Perl interpreter program on the Penn State Personal, Clubs and Departmental servers is /usr/local/bin/perl. This means the first line of every Perl script .pl and .cgi file should be: #!/usr/local/bin/perl

   When you save the guestbook.pl file, make sure you save it as a Text Document (.txt) format or plain text file, not Rich Text Format (.rtf) or Unicode.

   If there is a setting for the Encoding, make sure it is set to ANSI, US ASCII or Western, not Unicode or UTF-8. Make sure the filename doesn't change as some programs may want to rename the file to end in .txt rather than .pl.

   Finally, the script will need to be saved in Unix line ending format. Unix, Windows and Macintosh each use different byte values to indicate the end of a line in a text file. Many text editors do not know how to save in Unix line ending format, so the files will need to be converted during upload to the servers. After saving a file in the regular format for your system, you can convert a text file to Unix format during upload by using SSH Secure File Transfer or MacSFTP in a special mode called "ASCII" or "Text". See how below under "To convert .cgi and .pl files to Unix format."

   Text editors you can use and how they handle Unix line ending format
   If you use	You can use	Open Unix formatted files	Save Text Document (.txt) files in Unix format
   Windows (95 or newer)	Notepad	No (*)	No (**)
   	Wordpad	Yes	No (**)
   	DOS Edit	Yes	No (**)
   Macintosh Classic (8.x and 9.x)	SimpleText	No (*)	No (**)
   	BBEdit	Yes	Yes
   Macintosh OS X	TextEdit	Yes	Yes
   	WorldText	Yes	Yes
   	BBEdit	Yes	Yes
   Unix (or Linux)	vi	Yes	Yes
   	emacs	Yes	Yes
   	pico	Yes	Yes
   * - If you try to open a Unix formatted file with this editor, the text will look jumbled with block symbols.
   ** - You will need to convert the file to Unix format before using as a CGI script (.pl or .cgi file).

    

6. Make the following changes to the guestbook.pl file. Use your own Penn State Access Account userid in place of the example userid, xyz123.

   This line:	should be changed to read:
   #!/usr/bin/perl	#!/usr/local/bin/perl
   $guestbookurl -The URL address of your guestbook.html file	$guestbookurl="http://www.personal.psu.edu/users/x/y/xyz123/scripts/guestbook.html";
   $guestbookreal - The system location of your guestbook.html file	$guestbookreal="/pass/users/x/y/xyz123/www/scripts/guestbook.html";
   $guestlog- The system location of your guestlog.html file	$guestlog="/pass/users/x/y/xyz123/www/scripts/guestlog.html";
   $cgiurl- The URL portion of the address to the guestbook.pl file	$cgiurl="http://test.scripts.psu.edu/users/x/y/xyz123/scripts/guestbook.pl";

    

7. Open the guestbook.html and addguest.html files. You can use the same text editor as you used to edit the guestbook.pl file. You can also use an HTML editor such as Dreamweaver, but these directions are for a text editor. Make the following changes, followed by any other recommended changes in the README file. Please use your own Penn State Access Account userid in place of the example userid, xyz123.

   In this file:	change this line:	to read:
   addguest.html	action="http://your.host.com/cgi-bin/guestbook.pl"	action="http://test.scripts.psu.edu/users/x/y/xyz123/scripts/guestbook.pl"
   guestbook.html	<a href="addguest.html">	<a href="http://test.scripts.psu.edu/users/x/y/xyz123/scripts/addguest.html">
   guestbook.html	<a href="../">	Change this line to refer to your home page.

    

8. Using the file transfer method of your choice, log in to your Web space.

   For instructions on transferring these files to your Web space, see question 2.4 of our Web Frequently Asked Questions.

   1. Make sure you are within your "www" folder.

   2. Make a new folder.

   3. Name this folder "scripts" (You can name this folder anything you like, in this example we are calling it "scripts").

   4. Double click on the scripts folder to move into that folder (in the PASS Explorer on the Penn State Portal, select the scripts folder and click the "Change To Selected Folder" button).

   5. Transfer your edited files to this scripts folder.

   To convert .cgi and .pl files to Unix format during upload, do the following: In Windows, use SSH Secure File Transfer, and set to "ASCII" mode: Connect to your site and change to the "scripts" folder. Under the "Operation" menu, select "File Transfer Mode" and then "ASCII". Upload your .cgi and .pl files. Afterwards, go back to "Auto Select" in that same menu. It will need to be "Auto Select" or "Binary" for .gif and .jpg image files. It can be in any setting for .html and .htm Web page files. In Macintosh, use MacSFTP (at least version 1.0.6), and "Force Text transfers" Connect to your site and change to the "scripts" folder. Check "Session" -> "Force Text transfers" from the MacSFTP menu at the top of the screen. Upload your .cgi and .pl files. Afterwards, uncheck "Session" -> "Force Text transfers" before uploading any .gif and .jpg image files. It can be in either setting for .html and .htm Web page files.

    

9. To set permissions correctly, you will need to:

   • make the guestbook.pl file executable by all and
   • allow test.scripts.psu.edu to make changes to your guestbook.html and guestlog.html files.

   For security reasons, the Personal Web server is configured in such a way that a typical user cannot make changes to the files in your www folder. For CGI scripts to make changes, the Web server program must be given write permission to the data files. The Web server program on http://test.scripts.psu.edu/ runs with the identity of a "user" called test.scripts.psu.edu, and is in the group called test.scripts.psu.edu. You should give the group test.scripts.psu.edu write permission to files your CGI program needs to change. You should not give write access to everyone to limit the possibility of someone accidentally or maliciously changing or deleting your CGI data. The Secure Server (at https://www.work.psu.edu/ on the Web) provides a way to set permissions for test.scripts.psu.edu, so that the script can run and save changes your visitors make when they use your script. For reading or executing files, it is sufficient to give the Web server program access by giving everyone Read and eXecute permissions (see below). The "user" test.scripts.psu.edu is also in the group called access, which is the group all Penn State Access Accounts are in.

   To set the guestbook.pl file with execute permission:

   1. Open the PASS Explorer in a new tab or window, so you can follow along with these directions. You may need to login with your Penn State Access Account userid and password.
   2. Browse to your personal Web space "www" folder, then to the "scripts" folder that contains your CGI script.
   3. Select guestbook.pl. Press the "Info" button. Then press the "Go to permissions" button in the resulting window.
   4. Select "Web Application File Permissions" and then press the "Next >" button.
   5. Select "Set Permissions Needed for CGI" and then press the "Next >" button.
   6. Select "Grant permissions for the test.scripts.psu.edu server to execute this file as a CGI script" and then press the "Apply" button.
   7. If all is successful, a "Permissions Successfully Applied" message shows as well as a permissions summary. In the summary, the "File is executable" message should appear under "Flags."

   To set the guestbook.html and guestlog.html files with write permission:

   1. Press "Select another file" and browse back up to the "scripts" folder again.
   2. Select guestbook.html. Press the "Info" button, then press the "Go to permissions" button.
   3. Choose "Web Application File Permissions" and press the "Next >" button.
   4. Choose "Set Permissions Needed for CGI" and press the "Next >" button.
   5. Choose "Grant permissions for the test.scripts.psu.edu server to write to this file as a data file" and then press the "Apply" button.
   6. If successful, the test.scripts.psu.edu group should appear under the "Servers" column of the "Read/Write Access Permission" row of the permissions summary.
   7. Repeat these steps for guestbook.log.

    

10. Test out your form.

    1. Go to: http://www.personal.psu.edu/userid/scripts/guestbook.html (where userid represents your Penn State Access Account userid)
       
    2. Click the "add" button.
    3. Type in some information in the form.
    4. Click "submit."
    5. Go back to the Guestbook page and
    6. Click on the "reload" button.

     

11. If you encounter any problems, you should consult the troubleshooting section of the general CGI procedure for advice. If you still have trouble, contact webmaster@psu.edu.