Common Gateway Interface (CGI)

CGI programs are most commonly used with HTML FORM's, and provide the server interface that receives the form variables and processes them.

Many people think that CGI means Perl. Nothing could be further from the truth. CGI simply specifies an interface convention, and the programs that work with CGI can be written in virtually any language.

The only requirement for being able to act as a CGI program is the ability to read from Standard Input ( stdin), or the ability to access Environment variables.

Access to CGI programs and scripts must be made via the " cgiwrap" process. The following steps describe how to implement a program using " cgiwrap".

  1. To use the " cgiwrap" process:
    1. Create a sub-directory within your " public_html" directory called " cgi-bin".
    2. The permissions for this directory should be 0711. It does not need to be world readable, but it must be world executable.
    3. Place your executable scripts and/or programs within this directory. These files should have permissions 0700. They must be executable, but only need to be executable by you.
    4. Code the " ACTION" URL within your " <FORM>" tag as:
      <FORM ACTION="/cgi-bin/cgiwrap/username/CGIprogram"
         METHOD= [ GET | POST ] >
      " username" is your user ID that you use to login. " CGIprogram" is the name of your executable program or script. Note, that unlike the URL for your Home Page, the username in the " <FORM>" tag does not start with a tilde (~) character.
      • " METHOD=POST" can only be used within a " <FORM>" tag.
      • " METHOD=GET" can be used directly within a " <FORM>" tag and implicitly in the URL of an HTTP link.
      • " METHOD=POST " provides any parameters as " keyword=value" pairs in a single input line in Standard Input (stdin).
      • " METHOD=GET" provides the same input string in an Environment variable called " QUERY_STRING".
      • Some browsers also provide a value for an Environment variable called " CONTENT_LENGTH". This is not universal, and should be treated as informational only.
      • Multiple keyword=value pairs are separated by a single ampersand (&) character.
      • Blanks or spaces in keywords or values are received as a plus (+) sign.
      • Most special characters are received as a two-digit hexadecimal value preceded by a per-cent (%) sign.
      • Multi-line values have their lines separated by a carriage-return/line-feedpair, encoded in hexadecimal as " %0D%0A".
    5. Note that the URL in this tag does NOT specify the name of a Web server.
  2. The " cgiwrap" process does a few basic security checks, then executes your script or program, running under your user ID.

    The program or script must:
    • be executable;
    • not be setuid or setgid;
    • be a physical file in " ~username/public_html/cgi-bin";
    • not be a symbolic link to any other file.
    • be owned by the username listed in the " ACTION" URL.
  3. Since the " cgiwrap" process executes your script or program under your own user ID, that script or program has the same access to files as you do when you are logged on.

    This means that any files that you need to access should be writable only by you. They do not have to be world writable!
  4. You can create sub-directories within your cgi-bin directory. These should also have permission 0711. In this case, code the " ACTION" URL within your " <FORM>" tag as:
    <FORM ACTION="/cgi-bin/cgiwrap/username/Directory/CGIprogram">
  5. If you need full control of the HTML Headers produced by your script/program, you can substitute " nph-cgiwrap" for the normal cgiwrap program. This is usually only needed if you wish to create your own error handlers for problems with your personal web content. eg. You want to provide your own handling for a " 404 - page not found" error. Note that providing this support will require other things. Anyone wanting to do this should read the Apache Manual very closely. Hint: The Webmaster will not help you!
  6. The following note only applies to people preparing content for the Departmental Web Site:
    • There are additional testing requirements for executable web content for the Departmental server.
    • Contact the Computer Science Systems Administrator for assistance. Isn't this becoming a recurring theme?
    • Remember that while most executable content is interchangeable between the servers, PHP is not. PHP is only available on the User server.
  7. Be sure to read the Testing section !