AuroraCGI Documentation
This documentation is based on the README file for the SafePERL-CGI extension.
|
New CGI script available: mailform lets you
mail form contents and display a new page simultaneously.
|
Table of Contents
Introduction
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.
Capabilities
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.
Perl programming in the AuroraCGI environment
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.
Restricted operators
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.
AuroraCGI Extensions
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.
Remember: According to the Aurora Project Interface Standards, all web pages served from the Case Campus Web Server must have the Aurora Header and Footer and contain the proper owner information at the bottom of the page.
See Sample Program #1 as a usage example of AURORAheader() and AURORAfooter(). (Run sample program #1.)
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.
Installing your CGI program
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.
Example of writing and installing a AuroraCGI program
Here are the steps to follow to write and install an AuroraCGI program:
- Write the program. Sample programs are provided.
- 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").
- FTP to wwwftp.case.edu and log in using your APAS ID and password.
- If this is your first AuroraCGI program, you need to create three directories:
Follow the documentation for your FTP client to create these directories.
- Upload the AuroraCGI program to the
/cgi/bin directory.
- Upload the input and output files to the
/cgi/out directory.
- Test out your program.
|
