The CGI is the simplest, and most common, way to put dynamic content on your web site. This week's column will be an introduction to setting up CGI on your Apache Web server and getting started writing
With this column Rich Bowen begins his weekly look at basic tasks that every Apache Webmaster must face. Rich is the author of Apache Server Unleashed.
The CGI (Common Gateway Interface) is the simplest, and most common, way to put
dynamic content on your web site. This week's column will be an introduction
to setting up CGI on your Apache Web server and getting started writing
Configuring Apache to Permit CGI
In order to get your CGI programs to work properly, you'll need to have Apache
configured to permit CGI execution. There are several ways to do this.
ScriptAlias directive tells Apache that a particular directory is
set aside for CGI programs. Apache will assume that every file in this
directory is a CGI program and will attempt to execute it, when that particular
resource is requested by a client.
ScriptAlias direcive looks like:
ScriptAlias /cgi-bin/ /usr/local/apache/cgi-bin/
The example shown is from your default
httpd.conf configuration file, if you
installed Apache in the default location.
ScriptAlias directive is much like the
Alias directive, which defines
a URL prefix that is to mapped to a particular directory.
are usually used for directories that are outside of the
The difference between
ScriptAlias has the added meaning that everything under that URL prefix
will be considered a CGI program.
So, the example above tells Apache that any request
for a resource beginning with
/cgi-bin/ should be served from the directory
/usr/local/apache/cgi-bin/, and should be treated as a CGI program.
For example, if the URL
http://dev.rcbowen.com/cgi-bin/test.pl is requested,
Apache will attempt to execute the file
return the output. Of course, the file will have to exist, and be executable,
and return output in a particular way, or Apache will return an error message.
CGI Outside of ScriptAlias Directories
Occasionally you will want to have CGI programs outside of
directories. Usually, this will be for the purpose of letting users have web
content in their home directories with the
UserDir directive. If they
want to have their own CGI programs, but don't have access to the main
cgi-bin directory, they will need to be able to run CGI programs
.htaccess file is a way to set configuration directives on a per-directory
basis. When Apache serves a resource, it looks in the directory from which it
is serving a file for a file called
.htaccess, and, if it finds it, it will
apply directives found therein.
.htaccess files can be permitted with the
AllowOverride directive, which specifies what types of directives
can appear in these files, or if they are not allowed at all. To permit
the directive we will need for this purpose, the following configuration
will be needed:
.htaccess file, you'll need the following directive:
which tells Apache that execution of CGI programs is permitted in this
Explicitly using Options to Permit CGI Execution
You could explicitly use the
directive, inside your main server
configuration file, to specify that CGI execution was permitted in a particular
You might do this if, for some reason, you really wanted to serve CGI out of a
document directory. The
ScriptAlias directive is a combination
Alias directive and an
Options +ExecCGI directive, so this is
ScriptAlias directive without the
Writing a CGI Program
There are two main differences between regular programming, and CGI programming.
First, all output from your CGI program must be preceeded by a MIME-type header.
This is HTTP header that tells the client what sort of content it is receiving.
Most of the time, this will look like:
Secondly, your output needs to be in HTML, or some other format that a browser
will be able to display. Most of the time, this will be HTML, but occasionally
you might write a CGI program that outputs a gif image, or other non-HTML content.
Apart from those two things, writing a CGI program will look a lot like any other
program that you might write.
Your First CGI Program
The following is an example CGI program that prints one line to your browser.
Type in the following, save it to a file called
first.pl, and put it in your
print "Content-type: text/html\r\n\r\n";
print "Hello, World.";
Even if you are not familiar with Perl, you should be able to see what is happening
here. The first line tells Apache (or whatever shell you happen to be running
under) that this program can be executed by feeding the file to the interpreter
found at the location
/usr/bin/perl. The second line prints the content-type
declaration we talked about, followed by two carriage-return newline pairs. This
puts a blank line after the header, to indicate the end of the HTTP headers, and
the beginning of the body. The third line prints the string ''Hello, World.'' And
that's the end of it.
If you open your favorite browser and tell it to get the address
or wherever you put your file, you will see the one line
Hello, World. appear
in your browser window. It's not very exciting, but once you get that working,
you'll have a good chance of getting just about anything working.
But it's Still Not Working!
If your program still is not working, here are some of the things that you need
to look for in order to resolve your problem.
Remember that the server does not run as you. That is, when the server starts up,
it is running with the permissions of an unpriveleged user--usually
www--and so it will need extra permissions to execute files that are owned
by you. Usually, the way to give a file sufficient permissions to be executed
nobody is to give everyone execute permission on the file:
chmod a+x first.pl
Also, if your program reads from, or writes to, any other files, those files
will need to have the correct permissions to permit this.
When you run a program from your command line, you have certain information that
is passed to the shell without you thinking about it. For example, you have a path,
which tells the shell where it can look for files that you reference.
When a program runs through the web server as a CGI program, it does not have that
path. Any programs that you invoke in your CGI program (like sendmail, for example)
will need to be specified by a full path, so that the shell can find them
when it attempts to execute your CGI program.
Most of the time when a CGI program fails, it's because of a problem with the
program itself. This is particularly true once you get the hang of this CGI stuff,
and no longer make the above two mistakes. Always attempt to run your program
from the command line before you test if via a browser. This will elimate most
of your problems, and will prevent having to look through cryptic error logs.
For More Information
There are a large number of CGI resources on the Web. You can discuss CGI
problems with other users on the Usenet group
comp.infosystems.www.authoring.cgi. And the -servers mailing list from the
HTML Writers Guild is a great source of answers to your questions. You can
find out more at http://www.hwg.org/lists/hwg-servers/.
When you post a question about a CGI problem that you're having, whether
to a mailing list, or to a newsgroup, make sure you provide enough information
about what happened, what you expected to happen, and how what actually happened
was different, what server you're running, what language your CGI program
was in, and, if possible, the offending code. This will make finding your
problem much simpler.
Rich Bowen is the Director of Web Application Development at The Creative Group and the author of Apache Server Unleashed.