Table of Contents
The Common Gateway Interface (CGI) is a specification that allows an executable program on a web server to interact with a user’s browser. The common uses of CGI programs are to process data submitted from HTML forms and to create dynamic content to display to web browsers.
ITS now provides a CGI service to users, departments, projects and other groups via the UNC home page, where end users can run CGI programs out of a special directory in their AFS home directories or departmental or group AFS filespace with permissions limited in order to maintain the necessary security of the web server. This document provides instructions on how to obtain access to and use this service. It also describes how security restrictions impact this service.
Departments and other groups needing to set up CGI programs in their departmental AFS filespace may Submit a Help Request . Include the name of the directory under /afs/isis.unc.edu/depts/ in which you intend to store your CGI programs. Also include a short characteristic which distinguishes this directory’s purpose or projects from others which may exist for the same department or group. This distinguishing characteristic will be used to set up a new instance of your departmental group id under which your CGI programs will run. This directory and the departmental group id must both already exist.
For example, assume the Exobiology department has two major divisions: Mars and Europa. It might make sense that the associated groups would develop their web infrastructures independently, and thus may want separate CGI directories. The Mars group may want to set up their CGI programs in /afs/isis.unc.edu/depts/xbio/mars/cgi-bin to be run under the xbio.cgi-mars id. In this case, cgi-mars is the distinguishing characteristic of the xbio.cgi-mars instance of the xbio departmental group id. On the other hand, the Europa group might use the /afs/isis.unc.edu/depts/xbio/europa/outreach/www-bin directory to store their CGI programs which might run under the xbio.cgi-europa instance of the xbio departmental id. They would indicate cgi-europa as their distinguishing characteristic.
The path to your cgi-bin directory determines what ScriptAlias you use in your URL so the web server can find your program and the relevant information about your cgi instance. The URL will take the form, generally, of http://www.unc.edu/ScriptAlias/more/path/info/programname?parm=val . Which ScriptAlias you use depends on the path to your program. They are shown in the following table.
If the URL contains /auth/ before the ScriptAlias (e.g., https://www.unc.edu/auth/dept-bin/xyz/… ) then the browser should prompt the user for an Onyen and password before the server will run the program. If the user authenticates successfully, the CGI program can get the user’s Onyen from the REMOTE_USER environment variable. Note also that https: can be used in the URL instead of http: to encrypt the communication between the web browser and server.
Except for using directories under /afs/isis.unc.edu/depts/xyz/… instead of user’s home directories, and URLs being http://www.unc.edu/dept-bin/xyz/… instead of http://www.unc.edu/usr-bin/onyen/… , departmental CGI access works pretty much the same as personal CGI access, which is discussed in the rest of this document.
You subscribe to the CGI service the same way you subscribe to most other services. Here is a brief walk-through of the subscription process:
1. Go to the onyen.unc.edu site and click the button Subscribe to services .
2. On the next page, enter your Onyen and password, and then click the Continue button.
3. You should see a list of available services, some to which you will already be subscribed. If you are already subscribed to the CGI service, it will appear in the Subscribed Services section. To subscribe to the CGI service, click the button labeled CGI in the Unsubscribed Services section.
5. The next screen will set up your CGI directory and other things required for you to use this service. Once the process is finished, you should see a Continue button. Click this button to return to the main Subscribe to services page. The CGI service should now be listed under Subscribed Services .
During the personal CGI subscription process, a special directory called public_cgi was created in your home directory. Any CGI programs you wish to use must be placed in this directory or a subdirectory you create under this directory.
Once you have put your CGI program in this location, you will be able to access the program using the following URL scheme:
Be sure to replace “onyen” with your Onyen and “cgiprogram” with the name of your CGI program.
Also during the subscription process, the system created a special instance of your Onyen called onyen.cgi . The .cgi instance of your Onyen is used only by the web servers and only when running your CGI programs. This provides a layer of security which keeps other users’ CGI programs and yours from interfering with each other.
- CGI programs must be in your public_cgi directory
- CGI programs must run as your onyen.cgi instance
ITS does not provide programming services and therefore cannot provide programming assistance. However, if your CGI environment is setup correctly but your CGI program does not work as you expect, the following information may be helpful when troubleshooting problems you might have with your CGI program.
1. Permissions: When the web server runs your CGI program, it obtains an AFS token for your onyen.cgi instance. In order for the web server to read and execute your CGI program, and for you to be able to make changes to your program, you need to make sure the AFS permissions on your public_cgi and any of its subdirectories have the correct AFS access control lists (ACLs). These are set up initially by the CGI subscription process, but you may have changed them since then. You can check the current directory’s ACLs with the following command:
fs listacl .
Assuming your current directory is your public_cgi directory, you should see at least the following ACLs listed:
For more information on how to read and change AFS permissions on your directories, refer to the document Introduction to AFS .
If your CGI program is being used to collect data (i.e. HTML form submissions), you usually want to store that data in a file. Because of the restricted security environment, any directory you wish to write data into (which can be a directory outside your public_cgi directory subtree) must be writable by your CGI user instance ( onyen.cgi ). Such a directory should have an ACL like the following for your onyen.cgi instance.
2. UNIX Permissions: Access to local (i.e., non-AFS files) depends solely on the user id (uid) and group id (gid) of the process. When the web server runs your CGI program, it sets your process’ uid to the unique uid of your onyen.cgi instance, but leaves the gid alone. It also sets the default umask (the set of bits that determine the access rights of newly created files) to 0600. Therefore your program can only access local files that any other process on the system can access, or that it creates for itself. If you don’t change the umask, only your onyen.cgi processes can access the files they create. This provides a level of protection between your processes and those of other CGI subscribers.
3. Quota: The space used by files in your public_cgi directory is part of your AFS quota (see the above Introduction to AFS document). While exceeding your quota will not prevent execution of your CGI program, you may have other problems as a result (i.e. not being able to save HTML form data to a file in your home directory).
4. Using Perl: Perl is an interpreted programming language that is commonly used to create CGI programs. If you wish to use Perl to create CGI programs for use on the www.unc.edu web servers, you should make sure the first line of the program references the Perl interpreter located in AFS package space. This line should look like this:
5. Mail: There was a problem with trying to send mail from CGI programs. Specifically, since the programs runs under your onyen.cgi instance rather than your regular Onyen, and since the available mailers don’t recognize onyen.cgi as a legitimate user, your mail would be rejected. This problem has been resolved, and you should now be able to send mail from CGI programs.
6. Architecture specific programs: If you have binary programs instead of scripts that you want to run as CGI programs, you must provide a version that is compatible with the architecture of the web servers. A simple Perl script like the following, placed in your public_cgi directory and called “sys.pl” for example, will get the web server to show you its system type when you browse to http://www.unc.edu/usr-bin/onyen/sys.pl
print "Content-type: text/plain\n\n";
print `uname -a`;
No doubt some day we’ll replace the www.unc.edu web servers with newer machines of a different architecture. AFS provides a neat trick to help you manage your programs through such a change. If you create a symbolic link in AFS that ends is “@sys”, AFS will change the “@sys” to the output of the /usr/afsws/bin/sys command when resolving the link. So if you are trying to provide a binary program, public_cgi/blah , for example, for both the sun4x_58 and i386_linux24 architectures (as returned by the /usr/afsws/bin/sys command), you could set up a link and two different binaries like so:
$ ls -l ~/public_cgi l
lrwxr-xr-x onyen.cgi group 536 Mar 21 08:30 blah -&> blah.@sys
-rwxr-xr-x onyen.cgi group 28346 Aug 17 2001 blah.sun4x_58
-rwxr-xr-x onyen.cgi group 32563 Aug 21 2001 blah.i386_linux24
When a web server running on a Solaris 8 system tries to use blah , it is going to get the blah.sun4x_58 program, but a program running on an x86-based Linux system will get the blah.i386_linux24 version of the program. On the other hand, a web server running an AIX system (i.e. rs_aix51), won’t find anything to run, which is arguably better than finding a binary for the wrong architecture. (Note: This same trick works anywhere in AFS and is not just when loading programs. It is handy for creating directory and file structures that are architecture neutral in appearance).
7. Error messages: Normally, the debugging and error messages CGI programs write to stderr go to the web server’s error log. Since access to these logs is unavailable to regular users, logging messages there is unhelpful in troubleshooting CGI problems. However, if you create a log directory under your public_cgi directory and make it writable by your onyen.cgi instance like so:
fs setacl ~/public_cgi/log onyen.cgi write
then the web server will redirect your CGI program’s stderr stream to append to the file ~/public_cgi/log/error.log , to which you have access. This should make it simpler for you to debug your CGI scripts. Once you have your scripts debugged, you may want to either remove the log directory or periodically clear out the error.log file. Otherwise it will grow until your AFS quota is used up.
8. Numbered Error Messages: Errors that occur during the execution of a CGI program will have to be dealt with by the owner or maintainer of the CGI program. Some errors, however, can occur before the CGI Access program is run, in which case a page is returned to the user’s browser that starts with some error code number followed by “Error in CGI Access.” These specific error codes are listed below.
101 “Master key file improperly configured.”
102 “Couldn’t open master key file.”
103 “Couldn’t read master key.”
104 “Couldn’t set XXX limit to nnn – mmm .”
104 “Couldn’t get XXX limit – mmm .”
105 “Can’t grok master key file, line nnn .”
106 “Couldn’t access user keys for ‘ onyen .cgi’.”
The errors above indicate internal problems with the CGI Access security environment that will have to be corrected by the webmaster staff.
107 “Couldn’t find key for ‘ dir ‘ path.”
This is most likely caused by an error in the URL. Check the spelling of the Onyen (the part of the URL between the slashes after /usr-bin/ ).
108 “Memory allocation failed.”
Another internal error while preparing to execute a CGI application. Try the URL again.
109 “Couldn’t stat fffff – nnn .”
The program indicated by the URL could not be examined, probably due to incorrect or insufficient access permissions. Check the ACLs on the program’s directory and it’s parent directories.
110 “Unexpected character in path ffffff char ”
The URL could not be associated with a program or script, and the routine which tries to figure out what program to run has become confused. Check the URL and try again.
111 “Couldn’t change pwd to fffff .”
The web server tried to set the current directory to the directory which contains the CGI application but could not. This is probably an AFS permission (ACL) problem.
112 “No program given.”
The URL indicated a request for the CGI environment, but did not indicate the specific CGI program to run. Check the URL and try again.
113 “CGI wrapper not installed properly.”
The web server has insufficient permissions to properly initialize the CGI environment. Correction will require intervention by the webmaster staff.
114 “Couldn’t determine AFS cell.”
There appears to be a problem with how AFS is configured on the web server. Correction will require intervention by the webmaster staff.
115 “Invalid master key/passwd for virtual cgi-bin access.”
The web server set its keys down someplace and can’t remember where it left them. A member of the webmaster’s staff will need to bring a flashlight to help look for the keys.
116 “Couldn’t get SCRIPT_URL.”
The SCRIPT_URL environment variable was not processed as expected by the web server. Without this information, we cannot determine the path to the correct CGI program to run.
117 “Handler not configured for xxx-bin requests.”
CGI Access supports URLs of the form http://www.unc.edu/usr-bin/onyen/… and http://www.unc.edu/dept-bin/dept/… , but not http://www.unc.edu/xxx-bin/… . Correct the URL and try again.
118 “User specified, but no program given.”
The URL specified a CGI user, but not the specific CGI program to run. Check the URL and try again.
119 “Couldn’t determine AFS cell.”
Just like 114, but for different reasons. There’s nothing you can do until this is corrected by the webmaster staff.
120 “Invalid account/passwd for virtual cgi-bin onyen .cgi.”
The web server could not get AFS tokens for onyen.cgi or dept.cgi-xxx . The owner of the CGI application may need to resubscribe to the CGI Service to correct this problem.
121 “Invalid uid for virtual cgi-bin onyen .cgi.”
The uid of record for onyen.cgi is less than 1024, and is therefore considered a security risk.
122 “Couldn’t execute pgmname – errormsg .”
The indicated program could not be loaded, perhaps because the file is not marked executable (try ” chmod u+x pgmname “), or the first line of the interpreted CGI script (the “#!” line) contains a typographical error. The owner of the script will have to correct this problem.
123 “Spaces and Tabs are not allowed before “#!” in the first line of a CGI script.”
124 “Carriage Return is not allowed before Line Feed on first line of a “#!”-style CGI script; probable Windows line termination.”
These are common problems encountered by people trying to use Windows editors to edit CGI or other scripts that are to run under UNIX. The owner of the script will have to correct these problems.
125 “Couldn’t set uid for virtual CGI user name(uid-number) .”
The web server tried to change the process uid to that of the id instance indicated, but couldn’t.