Writing CGIs for a BRICKServer 2 Web Appliance

Details

Written by SAGE First Inc.

Writing CGIs for a BRICKServer 2 web appliance is not the same as writing CGIs for other web servers. Because the BRICKServer 2 maintains multiple hosts and due to its very strict security model, there are changes that may be needed to existing CGIs to port them to a BRICKServer 2. This document hopes to make the reader familiar with the BRICKServer 2 CGI environment to facilitate porting.

All hosts on the BRICKServer 2 are maintained within the directory "/m1/http." When a host is created, a subdirectory of the host's name is created within this directory. As an example, if the host for a paticular site is named "ABC.COM," then all of its files are maintained within the directory "/m1/http/ABC.COM." A site of the name "XYZ.COM" uses the directory "/m1/http/XYZ.COM" for all of its files and subdirectories. This document will use the term home to refer to the main directory setup for any given host on the BRICKServer 2.

All home directories are protected from each other. If a CGI for host ABC.COM is running, it does not have access to any of the directories for host XYZ.COM. This protection comes from the BRICKServer 2's operating system enhancements and can not be bypassed (just try, I dare you to try).

When using a scripting language, such as PHP or Perl, there are two ways to execute the script. The first method is to mark the script executable and make the first line of the script one of the following (this first line is called a "sha-bang" in the UNIX world):

Language First line
PHP #!/ext/php
Perl #!/ext/pl
TCL #!/ext/tcl
Python #!/ext/py

The second method is to mark the script executable and have its name end with the proper extension:

Language Extension
PHP .php
Perl .pl
TCL .tcl
Python .py
Java .class

Pure executable programs, like C compiled code, do not require any "sha-bang" or extension to run.

CGIs are placed within two directories of a site's home directory, depending on their needs. The two directories are named "cgi-bin" and "cgi-pbin." These two directories are given different rights to allow for general scripting and scripting for more sensitive data (like order records for an online store).

The "cgi-bin" directory is used for fairly low security CGI scripts. Any scripts running from this directory have the following rights:

1) read from anything within the site's home directory, except the directories "cgi-pbin" and "cgi-pdata."

2) create, read, write or delete anything within the "cgi-data" directory.

3) execute anything within the "cgi-bin" and "cgi-pbin" directories.

The "cgi-pbin" directory is used for higher security CGI scripts. Any scripts running from this directory have the following rights:

1) read from anything within the site's home directory.

2) create or append anything within the "cgi-pdata" directory. Note that CGIs can not read or overwrite anything within this directory.

3) execute anything within the "cgi-bin" and "cgi-pbin" directories.

These access rights and the directory setup usually cause two problems for developers. First, one can not execute programs that are usually found on UNIX computers. Using "popen" in PHP, as an example, runs "/bin/sh" to perform its task and thus will not work on a BRICKServer 2. Second, since the directory tree is not hidden from a script, accessing the two data directories is done with the paths "../cgi-data" or "../cgi-pdata" and NOT "/cgi-data" or "/cgi-pdata" (additional "../" prefixes may be needed, if the script is actually in a sub-directory of cgi-bin or cgi-pbin). Once past these two restrictions, and keeping in mind the above rights, CGIs move smoothly to a BRICKServer 2 from other web systems.

Sample CGI’s for a BRICKServer 2 web appliance.

Creating a file and writing to it:

C – glib version 2.2.5

For best results, C should be compiled with gcc version 2.95.3.

#include <stdio.h>
#include <unistd.h>

int main(int argc, char *argv[])
{
int id;

id=creat("../cgi-data/sample", 0666);
write(id, "Sample output line\n", 19);
close(id);

return 0;
}

Perl Version 5.8

This file starts with a sha-bang, the file does not have to have a ".pl" extension on it. It can be named anything.

WARNING:

Do not try to open files for append in the "cgi-pdata" directory with Perl. The Perl interpreter will automatically add a read or write attribute to the final OS level call which will cause it to fail!   The BRICKServer 2 access tables do not allow for reading or destructive writes (non-append version) to files in the "cgi-pdata" directory.


“cgi-data” appends work fine with Perl.

#!/ext/pl

open $f, ">../cgi-data/sample";
print { $f } "Sample output line\n";
close $f;

exit;

PHP Version 4.2.3

This file starts with a sha-bang, the file does not have to have a ".php" extension on it. It can be named anything.

The PHP.INI file is read from within the interpreter unless you place your own ini file in the cgi-data directory named php.ini, which can be acquired from http://www.php.net.

<?
$f=fopen("../cgi-data/sample", "w");
fwrite($f, "Sample output line\n");
fclose($f);
?>

TCL Version 8.4.1

This file starts with a sha-bang, the file does not have to have a ".tcl" extension on it. It can be named anything.

#!/ext/tcl
set chan [open ../cgi-data/sample w]
puts $chan "Sample output line\n"
close $chan

Python Version 1.5

This file starts with a sha-bang, the file does not have to have a ".py" extension on it. It can be named anything.

#!/ext/py
f=open('../cgi-data/py-example', 'w')
f.write('Sample output line\n')
f.close