CGIwrap is a gateway program that runs gateway programs. CGIwrap allows general users to use CGI scripts and HTML forms without compromising the security of the HTTP server. The scripts are run with the "permissions" of the user who owns the script, from the user's own directory. What all this means is that GWI users can now install and run (or crash and trash) their own CGI scripts and WWW forms without having to bug the webmaster to install them in the server's cgi-bin directory.

CGIwrap is accessed via a URL in an HTML document. The basic form of a CGIwrap URL for your personal webspace is: http://home.gwi.net/cgi-bin/cgiwrap/~username/scriptname.

CGIwrap is configured to run user scripts located in a "cgi-bin" directory located under the user's own public www directory. On Great Works Internet this would be under the public/www directory in a user's home directory. Numerous security checks are per formed on the script and if any checks fail, the script is not executed, and generally terse and semi-informative error messages are returned to the browser to aid in debugging (see "Bugs" below).

While CGIwrap doesn't remove all the potential security risks of user-written CGI scripts, it does assure that CGI scripts are not going to create system-wide problems because the scripts can't get into any more trouble than the user can get into themselves (which in some cases can be quite a bit!). This is because scripts run under CGIwrap execute with the user's UID (User ID) and GID (Group ID) and not the UID/GID of the Web Server (root/www) like ordinary CGI scripts. In other words, if a script trashes files or directories, they are at least the user's files and directories and not our valuable system data.

NOTE! Whenever using a CGI script that calls another file from your directory, it is important to use the path ~username.

The Inevitable Caveat

For the system administrator, CGIwrap performs extensive logging of user CGI script execution as well as offering an "allow/deny" function. This means we can restrict access to CGIwrap on an individual user basis. Currently all GWI users are in the "allow" category and any attempts to execute malicious/nasty scripts will undoubtedly lead to a user being stuck in the "deny" category.

In short, CGIwrap allows you to write, install, and run your own CGI scripts without needing to contact us.

The following instructions are for setting up your directories and scripts for execution on Great Works Internet. It is assumed that you are familiar with writing CGI scripts and writing HTML documents, and that you have also set up the correct world wide web directory structure under your home directory.

For this example, the cgi-bin script is "guestbook.pl". The user id is "waldo".

• First, FTP to your webspace, cd to public/www and create the directory "cgi-bin" (the cgi-bin directory must be named cgi-bin) if it does not exist.
  
• Using your FTP program, make sure the permissions on the cgi-bin directory are 755.
  
• Open your cgi-bin directory and upload the script "guestbook.pl" to it.
  
• Make sure the permissions on the script "guestbook.pl" are 755.
  

In this example, the script is executed using the following URL in the HTML file:

http://home.gwi.net/cgi-bin/cgiwrap/~waldo/guestbook.pl

So you can see how the various files and directories have been referenced, here are the operative variable definitions in guestbook.pl

• $guestbookurl = "http://home.gwi.net/~waldo/guestbook.html";
  
• $guestbookreal = "~waldo/public/www/guestbook.html";
  
• $guestlog = "~waldo/public/www/guestlog.html";
  
• $cgiurl = "http://home.gwi.net/cgi-bin/cgiwrap/~waldo/guestbook.pl";
  

(guestbook.pl is a script from Matt's Script Archive, an excellent source of well-written and *free* CGI scripts. guestbook.pl is written in perl which is a commonly-used language for writing CGI scripts.)

Bugs: Enemy, or Pie-Filling?

If you wish to see debugging output for your CGI, specify cgiwrapd instead of cgiwrap in your URL link. You'll get extensive debug output regarding your script, your environment, and any problems that occur during execution.

Using CGIwrap with binary data

If your CGI returns non-text data (i.e., binary data, images, sounds, etc.) you should specify nph-cgiwrap (or alternatively, for debugging output, nph-cgiwrapd) in place of cgiwrap in your URL link. You would use nph-cgiwrap if for example your CGI script returned a graphic hit-counter image or sound file.

Using forms with CGIwrap

To use a script from within a form, you must put the cgiwrap URL inside the FORM tag, cgiwrap can be used with both POST and GET type forms, but it is suggested you use the POST method, as GET forms are very limited in the amount of information they can pass to the form, but both methods are shown below.

Example form with CGIwrap

In our form example, user waldo wants the results of his guestbook form to be sent to script guestbook.pl for processing. We do not include the full form here, but enough to show the example for both a POST and a GET type form.

Sample POST form

<FORM METHOD="POST" ACTION="http://home.gwi.net/cgi-bin/cgiwrap/~waldo/guestbook.pl">
Form stuff goes here
</FORM>

Sample GET form

GET forms require you to add two hidden fields to your form, containing the username and scriptname.
<FORM METHOD="GET" ACTION="http://home.gwi.net/cgi-bin/cgiwrap">
<INPUT TYPE="hidden" NAME="user" VALUE="waldo">
<INPUT TYPE="hidden" NAME="script" VALUE="guestbook.pl">
</FORM>

Common Error Messages

CGIwrap Error: System Error: execv() failed

Error: No such file or directory (2)

If the script you're trying to execute is interpreted (e.g., perl), the path to the interpreter could not be found. For perl scripts, the interpreter should be #!/usr/bin/perl.

If you can't see the problem with the interpreter, then more than likely your script contains linefeeds (a ^M character) that UNIX is interpreting literally so your script looks for a non-existant interpreter such as #!/usr/bin/perl^M. This problem particular affects Windows users. The fix? Edit your CGIs in an UNIX environment, or be sure to upload your script as ASCII not BINARY.

Docs/Help/Info/Credits

CGIwrap was written by Nathan Neulinger (nneul@umr.edu). Thank You Nathan! You can check out http://cgiwrap.sourceforge.net/ for more information about CGIwrap.

For additional information about writing CGI scripts and HTLM/WWW stuff in general, check out the following sites:

http://en.wikipedia.org/wiki/HTML
http://www.htmlgoodies.com/primers/html/

Submit comments/questions/etc. about using CGIwrap to webmaster@gwi.net.