Apache Tutorial: Dynamic Content with CGI

 

Apache Tutorial: Dynamic Content with CGI

Introduction

The CGI (Common Gateway Interface) defines a way for a web server to interact with external content-generating programs, which are often referred to as CGI programs or CGI scripts.

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

The 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.

The ScriptAlias directive looks like:

ScriptAlias /cgi-bin/ /usr/local/apache2/cgi-bin/

The example above tells Apache that any request for a resource beginning with /cgi-bin/ should be served from the directory /usr/local/apache2/cgi-bin/, and should be treated as a CGI program.

Explicitly using Options to permit CGI execution

You could explicitly use the Options directive, inside your main server configuration file, to specify that CGI execution was permitted in a particular directory:

<Directory /usr/local/apache2/htdocs/somedir>
Options +ExecCGI
</Directory>

The above directive tells Apache to permit the execution of CGI files. You will also need to tell the server what files are CGI files. The following AddHandler directive tells the server to treat all files with the cgi or pl extension as CGI programs:

AddHandler cgi-script .cgi .pl

.htaccess files

The .htaccess tutorial shows how to activate CGI programs if you do not have access to httpd.conf.

User Directories

To allow CGI program execution for any file ending in .cgi in users' directories, you can use the following configuration.

<Directory /home/*/public_html>
Options +ExecCGI
AddHandler cgi-script .cgi
</Directory>

If you wish designate a cgi-bin subdirectory of a user's directory where everything will be treated as a CGI program, you can use the following.

<Directory /home/*/public_html/cgi-bin>
Options ExecCGI
SetHandler cgi-script
</Directory>

Writing a CGI program

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 cgi-bin directory.

#!/usr/bin/perl
print "Content-type: text/html/n/n";
print "Hello, World.";

If you open your browser and tell it to get the address

http://www.example.com/cgi-bin/first.pl

or wherever you put your file, you will see the one line Hello, World. appear in your browser window..

But it's still not working!

There are four basic things that you may see in your browser when you try to access your CGI program from the web:

The output of your CGI program

Great! That means everything worked fine. If the output is correct, but the browser is not processing it correctly, make sure you have the correct Content-Type set in your CGI program.

The source code of your CGI program or a "POST Method Not Allowed" message

That means that you have not properly configured Apache to process your CGI program. Reread the section on configuring Apache and try to find what you missed.

A message starting with "Forbidden"

That means that there is a permissions problem. Check the Apache error log and the section below on file permissions.

A message saying "Internal Server Error"

If you check the Apache error log, you will probably find that it says "Premature end of script headers", possibly along with an error message generated by your CGI program. In this case, you will want to check each of the below sections to see what might be preventing your CGI program from emitting the proper HTTP headers.

File permissions

Remember that the server does not run as you. That is, when the server starts up, it is running with the permissions of an unprivileged user - usually nobody, or 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 by 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.

Error logs

The error logs are your friend. Anything that goes wrong generates message in the error log. You should always look there first. If the place where you are hosting your web site does not permit you access to the error log, you should probably host your site somewhere else. Learn to read the error logs, and you'll find that almost all of your problems are quickly identified, and quickly solved.

CGI modules/libraries

When you write CGI programs, you should consider using a code library, or module, to do most of the grunt work for you. This leads to fewer errors, and faster development.

If you're writing CGI programs in C, there are a variety of options. One of these is the CGIC library, from http://www.boutell.com/cgic/