 |
Procedure for adding a CGI Script to your Web Site |
| ||||
General CGI Script Procedure | Guestbook Procedure
This page presents the general procedure for adding a script to your Web site. For specific directions on adding a guestbook to your site, refer to the Guestbook procedure.
Find a suitable script. Many are available, and you can find scripts to carry out most common functions with a Web search. You'll want to be sure to choose one that has adequate documentation, so that you'll know how to install it.
Make sure the script is written in the Perl language, intended to run as a CGI, and compatible with UNIX servers.
Find a file to download. Usually a script that uses multiple files will be packaged together in a compressed file, such as a Zip (.zip) file. Download the file or files to your local computer.
Unzip the file. You may need a program such as WinZip, PkZip or Stuffit Expander to open it.
For example, the Guestbook script zip file will contain the following files when opened:
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:
|
Read over all the documentation for the script you plan to install. 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. Reading and understanding the documentation is really the most important step to installing a script. Usually the documentation is in a file called "README" or "INSTALL".
Some steps may be different for Penn State, such as setting permissions. Please read below for advice on editing files, uploading files and setting permissions.
How to edit .pl (or .cgi) files
Many CGI scripts will require you to edit settings inside the .pl or .cgi script files to work on your site. In order to do so, you will need to use a program called a text editor. See the below table 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:
|
When saving changes to a .pl or .cgi script file, make sure you save as a Text Document (.txt) 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 ending in .txt rather than .pl or .cgi.
After saving changes, .pl and .cgi files must be converted to Unix line-ending format. Unix, Windows and Macintosh each use different byte values to indicate the end of a line in a text file. Some editors such as TextEdit on Mac OS X can save text files in Unix format. For the ones that cannot, including Wordpad, 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). | |||
How to edit .html files
Often you will have to make changes to your .html files. You can make changes to .html files using a program such as Dreamweaver or FrontPage, but most CGI script directions will ask you to use a text file editor. You can use the same text editor for .html files that you used for .pl or .cgi files.
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.
Make sure you are within your "www" folder.
Make a new folder.
Name this folder "scripts" (You can name this folder anything you like, in this example we are calling it "scripts").
Double click on the scripts folder to move into that folder (in PASS Explorer, select the scripts folder and click the "Change To Selected Folder" button).
Transfer your edited files to this scripts folder.
To convert .cgi and .pl files to Unix format during upload, do the following: |
To set permissions correctly, you will need to:
|
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 CGI files with execute permission:
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.
Browse to your personal Web space "www" folder, then to the folder that contains your CGI scripts.
Select one of your .pl or .cgi script files. Press the "Info" button. Then press the "Go to permissions" button in the resulting window.
Select "Web Application File Permissions" and then press the "Next >" button.
Select "Set Permissions Needed for CGI" and then press the "Next >" button.
Select "Grant permissions for the test.scripts.psu.edu server to execute this file as a CGI script" and then press the "Apply" button.
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."
Press the "Select another file" button at the top of the page to select another file and then repeat these steps for every .pl and .cgi file that needs to run as a CGI script.
To set data files with write permission:
Press "Select another file" and browse back up to the "scripts" folder again. For every file you need to give write permission to your script (the directions may ask you run 'chmod 666' or 'chmod a+rw' on the file), do the following:
Back up to the "scripts" folder again. For every folder you need to give write permission to your script (the directions may ask you run 'chmod 777' or 'chmod a+rwx' on the folder), do the following:
Test out your form.
Troubleshooting - Here are some common Web server errors and their usual meaning:
404 - File Not Found - The URL you entered does not match a file or script on the server. It may also be the case your page is in another folder.
NOTE: The "www" folder in your
PASS space is not present in the URL, so the file
|
403 - Forbidden - The permissions in PASS or in the Web server's configuration disallow viewing the requested URL. This means any of the following may be occuring:
An .html, .htm Web page file, .gif or .jpg image file does not have Read permission granted to the Web server program.
A .pl or .cgi file meant to execute does not have both Read and eXecute permission granted to the Web server program (or to everyone).
The folder the file is in or one of the parent folders the folder is in is not accessible by the Web server program because the eXecute permission is not granted. This permission is used as the access permission for folders.
There is an .htaccess file in one of the folders leading to the file that disallows reading the file or folder.
There is an .htaccess file in one of the folders leading to the file that is not readable by the Web server program.
The main Web server configuration disallows viewing the specific file or folder. NOTE: The Penn State Personal server, http://www.personal.psu.edu/ only permits CGI execution in the /cgi-bin/ folder.
An .htaccess file is a special file used by the Apache Web server software program that can customize specific settings for Web pages in the folder it is in and sub-folders. For instance you can turn on SSI parsing on specific files, restrict access to specific files and folders, set MIME types, enable password protection, HTTP redirects, and more. Visit the Apache httpd Web site documentation on .htaccess files for more. |
500 - Internal Server Error - This occurs whenever something "inside" has a problem, which can be one of many problems:
The file is not in Unix text format, or is in an encoding other than ASCII such as Unicode.
The first line of the script is refering to a program that is not on the server, or is mistyped.
The script ran, but did not complete the "HTTP headers." Usually a script will start by sending "Content-Type: text/html" followed by two end-of-line indicators, followed by the HTML for the page. The Content-Type line and blank line are called the HTTP headers (actually this is just part of the headers, the Web server program does the rest). If the HTTP headers are incomplete, because the script crashed or sent an error before the headers were completed, this error will occur. Common cases for this include:
There is a typo in the script that prevents it from running.
The script may be looking for Perl modules that are not available on the server. In this case, it sends an error and quits without completing the HTTP headers.
The script may have encountered a die instruction, which the programmer used to indicate a condition in which the script should send an error and quit, and did so without completing the headers. For instance, the guestbook script will die if the permissions are not set right on the guestbook.html and guestlog.html files when it tries to make changes to them.
There is an .htaccess file in the folder, or a parent folder that is improperly written, or it is attempting to change a setting not permitted by the main server configuration.
If you have difficulty, contact webmaster@psu.edu.