Information
Technology
Services

AuroraCGI Documentation

This documentation is based on the README file for the SafePERL-CGI extension.

Table of Contents

• Introduction
• Capabilities
• Perl programming in the AuroraCGI environment
• Restricted operators
• AuroraCGI Extensions
  • Sending Mail
  • Aurora Headers and Footers
  • Accessing Form Variables
• Installing your CGI program
• Example of writing and installing a AuroraCGI program

AuroraCGI is based on the SafePERL-CGI extension to PERL which allows web page maintaners to write CGI programs in Perl5 and to be run in a restricted, secure environment while protecting the integrity of the web server. It makes use of the Safe extension module for Perl5 -- any attempted unsafe operation in the CGI program is trapped and causes a fatal compile-time error. Wrappers and utility functions for useful but potentially unsafe operations (such as opening files and sending mail) are written in (unrestricted) PERL and then shared with the sanitised compartment. These wrappers were written by the staff of the old DMS team for AuroraCGI users.

Any APAS-ID user can place a perl program in their /cgi/bin directory (for example, a program named foo), and the URL

    http://www.case.edu/AuroraCGI/APAS-id/foo

will cause the web server to run the perl program /cgi/bin/foo as a CGI program under the userid of APAS-ID provided foo does not try to use any restricted perl operators. If foo is not specified in the URL line, AuroraCGI will attempt to access a script named index in the /cgi/bin directory.

The web server uses the Safe extension to Perl version 5 to run user-written CGI programs. For those of you who are familiar with version 4 of PERL but aren't familiar with Perl5, there aren't many differences that you are likely to notice. One is that the @ character now needs to be escaped (with a backslash "\" character) within double quotes -- Perl no longer guesses whether you meant to interpolate an array or not. Running perl with the -w flag will warn about this and many other potential errors besides. Although Perl5 is mostly backward compatible with Perl4, there are many new features in Perl5 which you can take advantage of: lexical variables, reference variables (arrays of arrays of hashes...), object oriented classes/methods, first class anonymous subs, closures and more.

Assistance with programming in the PERL language can be found at the PERL World Wide Web site.

There are many Perl operators not available to the compartment in which your CGI program is run. These mostly include operators which provide access to the operating system. The following list is not exhaustive but includes the most common excluded operators:

• system, `backticks`, exec, fork, syscall, signal handlers, pipes (including open(FOO, "|bar") and open(FOO, "bar|"))
• network access (socket, bind, connect, ...)
• File munging (rename, link, opendir, chown, ...)
• System V IPC (shared memory, message queues, semaphores)
• File tests (-r, -w, -l, ...)
• Calling perl on other files (require, use, do 'file')

Opening files for reading/writing is restricted. The PERL "open()" function is replaced by the "ropen()" function, which is subject to the following restrictions:

• Files opened for reading must be owned by the APAS-ID of the AuroraCGI program.
• Files opened for writing must be opened by using a filename containing no "/" characters. The filename is taken to live in the directory /cgi/out in your APAS directory and the file must already exist at the time the open is performed.

• Sending mail

  There is a subroutine available which allows the sending of mail from a CGI program. There are two forms of the mail() function call; the syntax is

  Usage:

  mail(RECIPIENT, SUBJECT, CONTENTS);
  mail(SENDER, RECIPIENT, SUBJECT, CONTENTS);
  

  For example,

      mail('foo@bar.baz', 'Test mail', "Hello world\n") or oops("mail failed");
      mail('my@email.address', "foo\@bar.baz", 'Test mail', "Hello world\n") or oops("mail failed");
  

  Note that @ interpolates an array when used in double quotes (""); if you want to hard-wire an email address with an @ in it then either use single quotes as in the example above or prefix the @ with a backslash ("$user\@wherever"). Note also that you gather the whole message together into one string to pass as the third argument. If the first form of the mail() call is used (without the Sender e-mail address), your APAS maintainer e-mail address is used.

• Aurora Headers and Footers

  Subroutines are provided to automatically generate the HTML code for the Aurora Headers and Footers. We recommend that you use these functions instead of the raw HTML code so that you will not have to change your AuroraCGI code when changes are made to the header and footer. LIT staff will be responsible for updating the AuroraCGI library routines to account for changes to the header and footer standards.

  Aurora Header

  Usage: print AURORAheader($title, $hOneTitle, $headTags, $bodyTags, $bodyAttrib);

  This library call will automatically insert the <HTML>, <HEAD>, and <BODY> tags as well as the HTML code for the Aurora Header image and imagemap. If you wish to insert metatags in the <HEAD> section or add parameters to the <BODY> tag, use the parameters to the function call as defined below:

  $title

  This is the title that appears in the <TITLE> tag, and, unless something is included in the second parameter, the <H1> tag in the <BODY> section as well.

  $headTags

  This item contains HTML code that will be in the <HEAD> section after the <TITLE> tag. HTML metatags would be inserted here.

  $bodyTags

  This item contains HTML code that will appear in the <BODY> section after the closing <H1> tag.

  $bodyAttrib

  Attributes for the <BODY> tag (eg, BACKGROUND, etc.) are included here.

  Aurora Footer

  Usage: print AURORAfooter($mailText, $mailURL, $copyright, $copyURL);

  This library call will automatically insert the </BODY>, and </HTML> tags as well as the HTML code for the Aurora Footer image, imagemap, and page owner information. If you wish to change the content of the page owner information at the bottom of the Aurora Footer, use the parameters to the function call as defined below:

  $mailText

  Text or HTML code that will appear as the link for the MAILTO URL in the footer. If this item is left blank, the e-mail address of the APAS ID maintainer will be inserted here.

  $mailURL

  URL that will appear as the link for the $mailText item in the footer. If this item is left blank, a MAILTO link to the APAS ID maintainer's e-mail address will be inserted here.

  $copyright

  Text or HTML code that will appear in the Copyright portion of the footer. If left blank, the standard "Copyright CWRU 1996" copyright notice will automatically be inserted here. If the word "off" is passed as this parameter, no copyright message or placeholder is printed.

  $copyURL

  URL that will be used as the HREF link in the $copyright item in the footer. If left blank, the standard copyright link will automatically be inserted here.

• Accessing Form Variables

  The data from GET and POST CGI form variables are imported into a namespace called FORM. For example, if there were parameters named 'foo1', 'foo2' and 'foo3', your AuroraCGI program would have the variables @FORM::foo1, $FORM::foo1, @FORM::foo2, $FORM::foo2, etc. Since AuroraCGI has no way of knowing whether you expect a multi- or single-valued parameter, it creates two variables for each parameter. One is an array, and contains all the values, and the other is a scalar containing the first member of the array. Use whichever one is appropriate. For example:

     print "Your name is $FORM::name\n";
     print "Your favorite colors are @FORM::colors\n";

  For keyword (a+b+c+d) lists (as the result of an <ISINDEX>), the variable @FORM::keywords is created. If the name of a form element contains a character other than letters or numbers, those characters are replaced by underscores in the variable name (eg. <INPUT NAME="weird name-here+" ...> would be accessed as "$FORM::weird_name_here_").

  See Sample Program #2 as a usage example of form variables. You can try out this form by using this page.

Once you have written and debugged your CGI program, put it in /cgi/bin in your home directory on the Aurora Case Web server (creating that directory if necessary). There is no need to include a leading '#!' line, nor will one be honored if you do. Supposing that your program is called foo, the URL which will cause the web server to invoke your program is

   http://www.case.edu/AuroraCGI/APAS-id/foo

When the web server runs your program it will run it with the privileges of your username.

Any use of a masked operator in your Perl program will trigger a compile time error (which your browser will display) and the program will not run at all. A "masked operator" is an operator which is restricted but which, unlike "open", is not aliased to a secure sanitized version. A list of these is included above. The error message will be something like

   opname trapped by operation mask at line ...

where opname is replaced by the name of the offending operator.

Here are the steps to follow to write and install an AuroraCGI program:

1. Write the program. Sample programs are provided.
2. Create any input and output files as well. If you need a file to store output, you need to create and upload a blank file (in the case of the sample program, "sample.txt").
3. FTP to wwwftp.case.edu and log in using your APAS ID and password.
4. If this is your first AuroraCGI program, you need to create three directories:
   • /cgi
   • /cgi/bin
   • /cgi/out
   Follow the documentation for your FTP client to create these directories.
5. Upload the AuroraCGI program to the /cgi/bin directory.
6. Upload the input and output files to the /cgi/out directory.
7. Test out your program.