Web Server: CGI Scripts
Apache supports the CGI (Common Gateway Interface) for running script files.
Script files which use Perl, and which do not rely on special software or configurations should run with minor changes. A number of script files written for other operating systems, however, may not run in the Windows environment without extensive modifications.
Instructions for using script files together with examples appear below. Perl is used as the script interpreter for the examples.
CGI Scripts Directory
Apache will run CGI scripts from the 'cgi-bin' directory. In the default MiniPortal installation, this is:
- C:/Program Files/InstantServers/MiniPortal/Apache/cgi-bin
User scripts should be placed into this directory. They can then be run under the web server by accessing:
- http://127.0.0.1/cgi-bin/scriptname
(e.g. to run 'hello.pl', place it into 'cgi-bin' and enter 'http://127.0.0.1/cgi-bin/hello.pl' into a web browser).
The Script Interpreter
CGI requires that the first line of each script (the 'shebang' line) must contain the characters '#!' followed by the path name for the script interpreter. On certain operating systems, if spaces occur in the path name, the entire path name must be enclosed by quotes.
The default shebang line for Perl is:
Note: if this does not work, use the complete Perl path name, e.g.
#!"C:/Program Files/InstantServers/MiniPortal/Perl/5.00503/bin/MSWin32-x86/perl"
This instructs CGI to run the Perl interpreter found by following the path name. Perl can also be directed to issue warning messages using the '-w' option as follows:
Although it is usually a good idea to use '-w', some Perl scripts have too many warning messages and will not run if '-w' is used.
If other interpreters are installed, any scripts in cgi-bin should have the shebang line adjusted to refer to the script interpreter executable.
If a shebang line is not used, the usual error message displayed by the web browser when attempting to access the script URL is '500 Internal Server Error'. The corresponding error message in the web server error log (logs/error.log) is "couldn't spawn child process: ..." where '...' is the path name of the script.
CGI Example Scripts
Example 1 tests that a CGI script is in the 'cgi-bin' directory, and that the 'shebang' line is correct. If this script already exists in the 'cgi-bin' directory, it can be executed. If not, copy and paste the code below into a file named 'hello.pl' in the 'cgi-bin' directory (and adjust the first line, if needed). Then run the script by entering 'http://127.0.0.1/cgi-bin/hello.pl' into a web browser.
|
#!perl
#
# Must issue a "response header" or else server error
# Using text-only in this example
print "Content-type: text/plain\n";
# And, always need a blank line to end the header
print "\n";
print "Hello, world\n";
|
Example 2 displays the environment variables available to the web server, sorted alphabetically. Note that this script uses the '-w' option. Also note that this script does not have a '.pl' filename extension. The filename extension is not necessary to run Perl script files since the 'shebang' line tells the web server to use Perl. As before, copy and paste the example code into a file named 'printenv' in the 'cgi-bin' directory. Then run the script by entering 'http://127.0.0.1/cgi-bin/printenv' into a web browser. The environment variables will be displayed in text format. (The extra lines of Perl code are to make sure the print statement works).
|
#!perl -w
##
## printenv -- demo CGI program which just prints its environment
##
print "Content-type: text/plain\n\n";
foreach $var (sort(keys(%ENV))) {
$val = $ENV{$var};
$val =~ s|\n|\\n|g;
$val =~ s|"|\\"|g;
print "${var}=\"${val}\"\n";
}
|
Note: you should delete this script when you are finished, since it makes 'internal' information, such as pathnames, publicly available (to anyone who runs the script).
Apache mod_perl Scripts
MiniPortal will also run Perl scripts (under Apache mod_perl) from the 'mod_perl' directory.
Note that use of mod_perl does require some knowledge of the mod_perl system, since it is different from straight CGI.
mod_perl has been configured so that the shebang line is optional.
Example 3 displays environment variables, though not sorted. No change was made to the shebang line since the script executes in the mod_perl directory.
|
#!perl -w
use strict;
my ($key, $val);
print "Content-type: text/html\n\n";
print << "END";
<HTML><HEAD>
<TITLE>Environment variables</TITLE>
</HEAD><BODY>
END
while (($key, $val) = each %ENV) {
print "$key = $val<BR>\n";
}
print "</BODY></HTML>\n";
|
To run the script, copy the example code into the file 'printenv2' in the 'mod_perl' directory. Then enter 'http://127.0.0.1/mod_perl/printenv2' in your browser. The environment variables will be displayed in html format.
Note: you should delete this script when you are finished, since it makes 'internal' information, such as pathnames, publicly available (to anyone who runs the script).
Administrative Scripts
MiniPortal runs administrative scripts from adm_perl. No user scripts should be placed into this directory.
|