The standard way to interface external applications with web servers is to use a common gateway interface (CGI). Unlike a plain HTML document, which returns only static information, a CGI program is executed in real-time so that HTML output can be generated dynamically. All users can put their own CGI programs on the iHome server, as discussed below. Or you can download different CGI programs from the internet. The following websites provide many ready-to-use CGI programs:

Writing CGI Programs

This is not as straightforward as dealing with static HTML pages and requires skills such as UNIX, as well as an understanding of the CGI programming environment. ITSC does not install, support, or help fix your CGI programs so you should be prepared to find resources from the internet to assist you, such as mailing lists, newsgroups, and some specific websites for CGI programming. You can use the following to find out more about setting up a CGI running environment, and developing, debugging, and controlling access to your programs:

Setting Up Your CGI Running Environment

You will need to enable your iHome account before you can set up your CGI programming environment.

CGI directory and program name

Place your CGI programs in a directory called cgi-bin in your root web space. Your CGI program filename should include the extension “.cgi”, “.pl” or “.php”. The URL to access your CGI program is:

http://ihome.ust.hk/~username/cgi-bin/filename.cgi

-or-

http://ihome.ust.hk/~username/cgi-bin/filename.pl

-or-

http://ihome.ust.hk/~username/cgi-bin/filename.php

For example, “ccdemo” puts the CGI program “testprog.cgi” under the “cgi-bin” directory of the root web space. The CGI program can be run with the following URL:

http://ihome.ust.hk/~ccdemo/cgi-bin/testprog.cgi
File permission and security

After you transfer your CGI program to the “cgi-bin” directory, make sure you have included the executable bit, otherwise the program cannot be executed. For details, refer to Change the permission mode of files via FileZilla.

Note that CGI programs run under your user id and access your account resources, such as files and directories. Therefore you don’t have to loosen permissions to read and write files through your CGI programs.

As CGI programs provide a way of passing information gathered from the web to a program running under your user id, you must be aware that a malfunctioning CGI program may accidentally allow someone to snoop through, remove, or modify files in your web directory. So be careful when putting up CGI programs. For details on writing secure CGI programs, read WWW Security FAQ.

Note: CGI program execution is provided by Apache’s suEXEC feature. This will check for security loopholes such as a “cgi-bin” directory and CGI programs that are world-writable or CGI programs with a symbolic link to other programs not owned by the user. A server error will then be returned during execution.

 

Developing CGI Programs

As the web server is a Solaris server, you must develop your CGI programs in a UNIX environment.

Programming languages

CGI programs can be written in any language supported by the web development platform, including compiled programming languages, such as C and C++; interpreted languages, such as Perl, PHP and the Bourne shell; and languages, such as Java. The environments of commonly used web development languages are:

  • Perl (/usr/local/bin/perl): Version 5.8.0. CGI.pm libraries are included in the standard Perl library and can be used in CGI programs written in Perl.
  • Java (/usr/java/bin/java): The default version of Java Development Kit is 1.4.
  • php (/usr/local/bin/php): php (cgi binary) version is 4.4.7. Here is an example:
    #!/usr/local/bin/php 
    <?php
      echo("Hello");
    ?>
Web directory

The wwwhome command returns the full path to your web space directory and can be used in CGI programs to refer to the location of your web directory. This is often needed when a CGI program has to read or write to other files in your web directory. The following examples demonstrate how the wwwhome command might be leveraged in a CGI program written in Perl.

The first example uses wwwhome to determine the location of a data file:

    #!/usr/local/bin/perl
    chop($wwwhome = `wwwhome`); 
    open(DATA,"$wwwhome/data.txt");
    ...

The second example uses wwwhome to add a new directory to the location where Perl libraries are found:

    #!/usr/local/bin/perl
    BEGIN { chop($wwwhome = `wwwhome`); }
    use lib "$wwwhome/mypackage";
    use MyPackage;
    ...

Debugging Your CGI Programs

It is normally difficult to debug CGI programs because you cannot study the output (standard output and error) for scripts that are failing to run properly.

Common CGI error messages

Here are the most common error messages resulting from broken CGI programs. iHome users can check these system messages via iHome – Personal Settings.

If you get this CGI error message… It may be because… And you should…
Method Not Allowed – The requested method POST is not allowed for the URL CGI program doesn’t have a .cgi , .pl or .php filename extension Rename your CGI program to include a .cgi , .pl or .php filename extension
Server Error – Premature end of script headers
  • CGI program isn’t executable
  • CGI program resides in a world- or group- writable directory
  • CGI program mislocates Perl interpreter
  • CGI program has bad end-of-line characters e.g.^M.
  • Make it executable. e.g. by using FileZilla
  • Remove world- or group write permission from directory.
  • Verify Perl programs begin #!/usr/local/bin/perl
  • Transfer all CGI programs from the PC using “ASCII” (or “text”) mode.
Server Error – malformed header from script
  • Error printing CGI header
  • Program prints something before header
  • CGI program has output buffering problems
  • Remove typos from Content-type header.
  • Debug your CGI program; make it print header first.
  • In Perl, set $|. In other languages, make sure print buffers are empty when you think they are.

Note: Internet Explorer 5.x customizes server error responses rather than displaying the actual text returned by the server.

Run CGI Programs in Debug Mode

The web server provides a CGI debugging running environment which lets you examine CGI running output.

  1. Create a subdirectory “cgiwrapd” in your root webspace
  2. Put your tested CGI programs inside the “cgiwrapd” directory
  3. Test running your CGI program with following URL:
http://ihome.ust.hk/cgi-bin/cgiwrapd/<username>/filename.cgi

For examples,

http://ihome.ust.hk/cgi-bin/cgiwrapd/ccdemo/testprog.cgi

The execution output, including error messages, will be displayed as text rather than HTML, as below. Examine the CGI environment variables and script output to debug your CGI programs. After you have verified the CGI program is running properly, you can move the corresponding CGI programs to the “cgi-bin” directory.

Initializing Logging
Redirecting STDERR to STDOUT

Setting SIGXCPU to default behaviour

Environment Variables:
     QUERY_STRING: ''
      SCRIPT_NAME: '/cgi-bin/cgiwrapd'
        PATH_INFO: '/ccdemo/testprog.cgi'
  PATH_TRANSLATED: '/usr/local/apache/htdocs/ccdemo/testprog.cgi'
      REMOTE_USER: ''
      REMOTE_HOST: ''
      REMOTE_ADDR: '143.89.103.42'

Trying to extract user from PATH_INFO.
Retrieved User Name:  'ccdemo'

User Data Retrieved:
     UserID: 'ccdemo'
        UID: '9481'
        GID: '100'
   Home Dir: '/home/ccdemo'

Script Base Directory:  '/home/ccdemo/public_html/cgiwrapd'
Trying to extract script from PATH_INFO
        Script Relative Path:  'testprog.cgi'
        Script Absolute Path:  '/home/ccdemo/public_html/cgiwrapd/testprog.cgi'

Fixing Environment Variables.

Environment Variables:
     QUERY_STRING: ''
      SCRIPT_NAME: '/cgi-bin/cgiwrapd/ccdemo/testprog.cgi'
        PATH_INFO: ''
  PATH_TRANSLATED: '/usr/local/apache/htdocs'
      REMOTE_USER: ''
      REMOTE_HOST: ''
      REMOTE_ADDR: '143.89.103.42'

UIDs/GIDs Changed To:
   RUID: '9481'
   EUID: '9481'
   RGID: '100'
   EGID: '100'

Changing current directory to '/home/ccdemo/public_html/cgiwrapd'

Output of script follows:
=====================================================
....

Note: CGI programs in the “cgiwrapd” directory are solely for debugging purpose. Access is open to anyone and access control cannot be enforced. It is therefore best if you remove items in this directory after debugging your CGI program.