Apache Guide: CGI dynamic pages

Profile

related Modules	related Directives
mod_alias mod_cgi	AddHandler Options ScriptAlias

The CGI (Public gateway interface [Common Gateway Interface]) defines the method by which the Web server interacts with the external content negotiation program, usually a CGI program or CGI script, which is the simplest and most common way to implement dynamic pages on a Web site. This article describes how to build CGI on the Apache Web server and how to write CGI programs.

Configure Apache to allow CGI

For CGI programs to function properly, Apache must be configured to allow CGI execution in several ways.

Scriptalias

ScriptAliasDirectives allow Apache to execute CGI programs in a particular directory. When a client requests a resource in this particular directory, Apache assumes that the file is a CGI program and tries to run it.

ScriptAliasThe instruction form is as follows:

ScriptAlias /cgi-bin/ /usr/local/apache/cgi-bin/

If Apache is installed to the default location, the configuration in the default configuration file will be the httpd.conf one described above. ScriptAliasdirectives define URL prefixes that map to a specific directory, Alias very similar to directives, and are typically used to specify DocumentRoot directories located outside of the directory, with the difference being that ScriptAlias any file in its URL prefix is considered a CGI program. So, the above example would indicate that Apache /cgi-bin/ should point to the /usr/local/apache/cgi-bin/ directory and treat it as a CGI program.

For example, if there is a URL for a http://www.example.com/cgi-bin/test.pl request, Apache will attempt to execute /usr/local/apache/cgi-bin/test.pl the file and return its output. Of course, this file must be present and executable and produce output in a specific way, otherwise Apache returns an error message.

CGI outside the Scriptalias directory

For security reasons, CGI programs are usually restricted to the ScriptAlias specified directory, so administrators can strictly control who can use CGI programs. However, if appropriate security method measures are taken, there is no reason not to allow CGI programs in other directories to run. For example, you might want users to UserDir store pages in the specified host directory, and they have their own CGI programs, but have no access to the cgi-bin directory, which creates the need to run CGI programs in other directories.

Use options to explicitly allow CGI execution

You can explicitly allow the execution of CGI in a particular directory in the primary server configuration file by using Options directives:

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

The above instructions enable Apache to allow CGI file execution. Also, you must tell the server which files are CGI files. The following AddHandler instruction tells the server that cgi all pl files with or suffix are CGI programs:

AddHandler cgi-script cgi pl

. htaccess file

.htaccessA file is a way to configure a directory. When Apache provides a resource, it looks for the file in the directory where the resource resides .htaccess , and if so, the instruction in it takes effect. The AllowOverride directive determines .htaccess whether the file is valid, specifies which directives can appear in it, or is not allowed at all. To do this, you need to configure this in the primary server configuration:

AllowOverride Options

In the .htaccess file, this configuration is required:

Options +ExecCGI

To enable Apache to allow the execution of CGI programs in this directory.

Writing CGI Programs

There are two main differences between writing a CGI program and a ' regular ' program.

First, there must be a MIME-type header in front of all the output of the CGI program, the HTTP header, indicating to the browser the type of content received, and in most cases, the shape:

Content-type: text/html

Second, the output requirements are in HTML form, or some other form that the browser can display. In most cases, the output is in HTML form, but occasionally a CGI program is written to output a GIF image or other non-HTML content.

In addition to these two points, writing CGI programs is roughly the same as writing other programs.

The first CGI program

This CGI program example prints a line of text in the browser. Save the following as a first.pl file and put it in your cgi-bin directory.

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

Even if you are unfamiliar with the Perl language, you should be able to see what it is doing. The first line tells Apache that this file can be /usr/bin/perl interpreted and executed using (or whatever shell you are using). The second line, print the description of the above requirements of the content type, and with two line breaks, leaving a blank line behind the head to show the end of the HTTP header. The third line, print the word ' Hello, world '. The program ends here.

Open your favorite browser and enter the address:

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

Alternatively, you can see a line in the browser window when you store the program in a different location Hello, World. . It's not very exciting, but once the program works, it can run any other program.

The program still can't run!

There are four possible scenarios in a browser that access a CGI program from the network:

The output of the CGI program

That's great! It means everything is fine.

The source code of the CGI program or a "POST Method not allowed" message

This means that Apache is not properly configured to execute CGI programs and re-read configuring Apache to see what is missing.

A message that begins with "Forbidden"

This indicates a problem with permissions. Refer to Apache error log and the permissions of the following files.

A "Internal Server Error" message

Check Apache error log to find the error message "Premature end of script headers" generated by the CGI program. For this, the following items need to be checked to find out why the correct HTTP header could not be generated.

Permissions for files

Remember, the server is not running as your user, that is, after the server is started, it has the privilege of being a non-privileged user-usually ' nobody ' or ' www '-and requires greater permissions to allow the execution of the file. In general, giving ' nobody ' sufficient permissions to execute the file is done by assigning the Everyone execute permission to the file:

chmod a+x first.pl

In addition, if additional files need to be read or written, the files must be given the correct permissions.

An exception is if the server is configured to use suEXEC. This program allows CGI programs to run with different user rights depending on the virtual host or user host directory in which they reside. suEXEC has extremely strict authorization checks, and any failure of the checksum will cause the CGI program to fail and produce "Internal Server Error". For this, you need to check the suEXEC log file to find out which security check is wrong.

Path information

When you execute a program at the command line, some information is automatically passed to the shell without you having to worry about it, such as a path that tells the shell where the file you are referencing can be found.

However, when a CGI program executes through a Web server, there is no such path, so any program that you reference in a CGI program (such as SendMail) must specify its full path so that the shell can find them to execute your CGI program.

A common usage is to indicate the interpreter (usually) in the first line of the CGI program perl , as in the form of:

#!/usr/bin/perl

It must be ensured that it does point to the interpreter.

Syntax error

Most CGI programs fail because of problems with the program itself, especially if the two errors have been eliminated and CGI hangs. Before testing with a browser, execute your program on the command line to discover most of the problems.

Error logging

The record of the error is your friend. Any error will be recorded in the error record, so you should check it first. If your web space provider does not allow access to error records, you should consider changing a space provider. Learn to read error records to quickly identify problems and resolve them quickly.

How does it work behind the scenes?

As your CGI programming gets deeper, understanding the behind-the-scenes operations, especially how browsers and servers communicate with others, becomes useful. Although successfully wrote a program to print ' Hello, world ', there is no practical use.

Environment variables

Environment variables are variables that are used everywhere when you use your computer, such as paths (a search path to the actual file to fill in your input), your user name, and your terminal type, and so on. At the command line input env , you can get a list of the environment variables for your standard day.

During the CGI process, the server and browser set environment variables such as browser type (Netscape, IE, Lynx), server type (Apache, IIS, WebSite), and the name of the CGI program to be executed, etc.

All of these variables are valid for CGI programmers, but only half of the client-server communication. Complete list of variables see http://hoohoo.ncsa.uiuc.edu/cgi/env.html

This simple CGI program lists all environment variables in the environment, and cgi-bin there are two similar programs in the Apache distribution. Note that some variables are required and some are optional, so you may see some variables that are not available in the official list. In addition, Apache provides a number of different methods to increase your private environment variables in the default supplied variables.

#!/usr/bin/perl
print "Content-type: text/html\n\n";
foreach $key (keys %ENV) {
print "$key --> $ENV{$key}<br>";
}

StdIn and stdout

Other communications between the server and the client are done through standard input devices ( STDIN ) and standard output devices ( STDOUT ). Typically, a STDIN keyboard or a file used by a program refers to a STDOUT console or monitor.

When you have POST a Web form into a CGI program, the data in the table is bundled into a special form by passing it to the STDIN CGI program, so that the program can process the data as if it were from a keyboard or a file.

This ' special form ' is simple, a field name and its value, in the middle with an equal sign (=) connection, multiple such fields are used with the symbol (&) to connect. Unconventional characters, such as spaces, symbols, and equals, are converted to their equivalent hexadecimal to avoid problems. The entire string is as follows:

name=Rich%20Bowen&city=Lexington&state=KY&sidekick=Squirrel%20Monkey

Sometimes, you will find that the URL is prefixed with such a string. This form causes the server to set environment variables QUERY_STRING , called requests, with the contents of this string GET . Your HTML table FORM sets properties in markup METHOD to specify the behavior of transferring data GET POST .

Next, your program must separate the string to get useful information. Fortunately, there are libraries and modules that can help you with this data, as well as processors that achieve other purposes for your CGI program.

CGI Modules/Libraries

When writing CGI programs, you should consider using code libraries or modules to do most of the trivial work to reduce errors and develop faster.

If the CGI program is written in Perl, the available modules are shown in CPAN, and the most commonly used modules are cgi.pm. You can also consider using Cgi::lite, which implements a minimum set of functions that are required in most programs

If you write a CGI program in C, there are a number of options, one of which is the Cgic library, from http://www.boutell.com/cgic/.

More information

There are a lot of CGI resources on the Internet. You can discuss CGI-related issues with others in the Usenet group comp.infosystems.www.authoring.cgi. HTML Writers Guild's-servers mailing list is an excellent resource for problem solving. More resources can be found at http://www.hwg.org/lists/hwg-servers/.

In addition, you can read the CGI specification, which has all the details of the CGI program operation, the original version see NCSA, and another update for the draft common Gateway Interface RFC project.

When you submit CGI-related questions to a mailing list or newsgroup, you should make sure that you provide enough information to more easily identify and resolve the problem, such as what happened, what results you want, what happens to what you expect, what server you run, what language the CGI program is written in, If possible, provide that nasty code.

Note that you should never submit a CGI-related issue to Apache bug database unless you believe that you are discovering a problem in the Apache source code.

Apache Guide: CGI dynamic pages