Penn State

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.

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

     

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

     

  3. 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:

    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:

    1. Run the Windows Explorer program, "Start" -> "Programs" -> "Windows Explorer"

    2. Select "Tools" -> "Folder Options..."

    3. Click the "View" tab at the top of the window that appears

    4. Under "Advanced settings:", uncheck "Hide extentions for known file types", then press "OK"

     

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

     

  5. 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:

    #!/usr/local/bin/perl

    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 useYou can useOpen Unix formatted filesSave Text Document (.txt) files in Unix format
    Windows (95 or newer)NotepadNo (*)No (**)
    WordpadYesNo (**)
    DOS EditYesNo (**)
    Macintosh Classic (8.x and 9.x)SimpleTextNo (*)No (**)
    BBEditYesYes
    Macintosh OS XTextEditYesYes
    WorldTextYesYes
    BBEditYesYes
    Unix (or Linux)viYesYes
    emacsYesYes
    picoYesYes
    * - 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. 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.

     

  7. 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 PASS Explorer, 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:

      1. Connect to your site and change to the "scripts" folder.

      2. Under the "Operation" menu, select "File Transfer Mode" and then "ASCII".

      3. Upload your .cgi and .pl files.

      4. 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"

      1. Connect to your site and change to the "scripts" folder.

      2. Check "Session" -> "Force Text transfers" from the MacSFTP menu at the top of the screen.

      3. Upload your .cgi and .pl files.

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

     

  8. 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:

    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 folder that contains your CGI scripts.

    3. Select one of your .pl or .cgi script files. 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."

    8. 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:

    1. 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:

      • Select the file from the file list
      • Press the "Info" button, then press the "Go to permissions" button
      • Choose "Web Application File Permissions" and press the "Next >" button.
      • Choose "Set Permissions Needed for CGI" and press the "Next >" button.
      • 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.
      • 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.
    2. 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:

      • Select the folder from the file list.
        • Note that you cannot select the folder you are viewing; to select it, double-click "^-- Up one folder" in the file list, then select the folder from the parent folder's list.
      • Press the "Info" button, then press the "Go to permissions" button
      • Choose "Web Application File Permissions" and press the "Next >" button.
      • Choose "Set Permissions Needed for CGI" and press the "Next >" button.
      • Choose "Grant permissions for the test.scripts.psu.edu server to write to all files in this folder as data files" and then press the "Apply" button.
      • 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.

     

  9. Test out your form.

    1. Go to: http://test.scripts.psu.edu/userid/scripts/your_script_form.html (where userid represents your Penn State Access Account userid and your_script_form.html is the first page of your script)
    2. Type in information and see if the script works.

     

  10. Troubleshooting - Here are some common Web server errors and their usual meaning:

     

  11. If you have difficulty, contact webmaster@psu.edu.


The Pennsylvania State University ©2003
This service is provided and maintained by
Information Technology Services (ITS) at Penn State.
This page was last updated on Saturday, July 19, 2003.

Have a question? See our list of contacts.