You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by rb...@locus.apache.org on 2000/11/12 14:15:52 UTC
cvs commit: httpd-docs-1.3/htdocs/manual/howto cgi_HOWTO.html
rbowen 00/11/12 05:15:52
Added: htdocs/manual/howto cgi_HOWTO.html
Log:
CGI tutorial. Initial contribution.
Revision Changes Path
1.1 httpd-docs-1.3/htdocs/manual/howto/cgi_HOWTO.html
Index: cgi_HOWTO.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<TITLE>Dynamic Content with CGI</TITLE>
<LINK REV="made" HREF="mailto:rbowen@rcbowen.com">
</HEAD>
<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
<BODY
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#000080"
ALINK="#FF0000"
>
<!--#include virtual="header.html" -->
<H1 ALIGN="CENTER">Dynamic Content with CGI</H1>
<A NAME="__index__"></A>
<!-- INDEX BEGIN -->
<UL>
<LI><A HREF="#dynamic content with cgi">Dynamic Content with CGI</A></LI>
<LI><A HREF="#configuring apache to permit cgi">Configuring Apache to permit CGI</A></LI>
<UL>
<LI><A HREF="#scriptalias">ScriptAlias</A></LI>
<LI><A HREF="#cgi outside of scriptalias directories">CGI outside of ScriptAlias directories</A></LI>
<UL>
<LI><A HREF="#explicitly using options to permit cgi execution">Explicitly using Options to permit CGI execution</A></LI>
<LI><A HREF="#.htaccess files">.htaccess files</A></LI>
</UL>
</UL>
<LI><A HREF="#writing a cgi program">Writing a CGI program</A></LI>
<UL>
<LI><A HREF="#your first cgi program">Your first CGI program</A></LI>
</UL>
<LI><A HREF="#but it's still not working!">But it's still not working!</A></LI>
<UL>
<LI><A HREF="#file permissions">File permissions</A></LI>
<LI><A HREF="#path information">Path information</A></LI>
<LI><A HREF="#syntax errors">Syntax errors</A></LI>
<LI><A HREF="#error logs">Error logs</A></LI>
</UL>
<LI><A HREF="#what's going on behind the scenes">What's going on behind the scenes?</A></LI>
<UL>
<LI><A HREF="#environment variables">Environment variables</A></LI>
<LI><A HREF="#stdin and stdout">STDIN and STDOUT</A></LI>
</UL>
<LI><A HREF="#cgi modules/libraries">CGI modules/libraries</A></LI>
<LI><A HREF="#for more information">For more information</A></LI>
</UL>
<!-- INDEX END -->
<HR>
<P>
<H1><A NAME="dynamic content with cgi">Dynamic Content with CGI</A></H1>
<P>The CGI (Common Gateway Interface) is the simplest, and most common, way to put
dynamic content on your web site. This document will be an introduction
to setting up CGI on your Apache web server, and getting started writing
CGI programs.</P>
<P>For all the gory details about CGI, see the CGI specification, at
<A HREF="http://hoohoo.ncsa.uiuc.edu/cgi/interface.html">http://hoohoo.ncsa.uiuc.edu/cgi/interface.html</A></P>
<P>
<HR>
<H1><A NAME="configuring apache to permit cgi">Configuring Apache to permit CGI</A></H1>
<P>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.</P>
<P>
<H2><A NAME="scriptalias">ScriptAlias</A></H2>
<P>The <CODE>ScriptAlias</CODE> 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.</P>
<P>The <CODE>ScriptAlias</CODE> direcive looks like:</P>
<PRE>
ScriptAlias /cgi-bin/ /usr/local/apache/cgi-bin/</PRE>
<P>The example shown is from your default <CODE>httpd.conf</CODE> configuration file, if you
installed Apache in the default location.
The <CODE>ScriptAlias</CODE> directive is much like the <CODE>Alias</CODE> directive, which defines
a URL prefix that is to mapped to a particular directory. <CODE>Alias</CODE> and <CODE>ScriptAlias</CODE>
are usually used for directories that are outside of the <CODE>DocumentRoot</CODE> directory.
The difference between <CODE>Alias</CODE> and <CODE>ScriptAlias</CODE> is
that <CODE>ScriptAlias</CODE> 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 <CODE>/cgi-bin/</CODE> should be served from the directory
<CODE>/usr/local/apache/cgi-bin/</CODE>, and should be treated as a CGI program.</P>
<P>For example, if the URL <CODE>http://dev.rcbowen.com/cgi-bin/test.pl</CODE> is requested,
Apache will attempt to execute the file <CODE>/usr/local/apache/cgi-bin/test.pl</CODE> and
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.</P>
<P>
<H2><A NAME="cgi outside of scriptalias directories">CGI outside of ScriptAlias directories</A></H2>
<P>Occasionally you will want to have CGI programs outside of <CODE>ScriptAlias</CODE>'ed
directories. Usually, this will be for the purpose of letting users have web
content in their home directories with the <CODE>UserDir</CODE> directive. If they
want to have their own CGI programs, but don't have access to the main
<CODE>cgi-bin</CODE> directory, they will need to be able to run CGI programs
elsewhere.</P>
<P>
<H3><A NAME="explicitly using options to permit cgi execution">Explicitly using Options to permit CGI execution</A></H3>
<P>You could explicitly use the <CODE>Options</CODE> directive, inside your main server
configuration file, to specify that CGI execution was permitted in a particular
directory:</P>
<PRE>
<Directory /usr/local/apache/htdocs/somedir>
Options +ExecCGI
</Directory></PRE>
<P>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.
This is done with the <CODE>AddHandler</CODE> directive:</P>
<PRE>
AddHandler cgi-script cgi pl</PRE>
<P>
<H3><A NAME=".htaccess files">.htaccess files</A></H3>
<P>A <CODE>.htaccess</CODE> 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 <CODE>.htaccess</CODE>, and, if it finds it, it will
apply directives found therein. <CODE>.htaccess</CODE> files can be permitted with the
<CODE>AllowOverride</CODE> 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 in your main server configuration:</P>
<PRE>
AllowOverride Options</PRE>
<P>In the <CODE>.htaccess</CODE> file, you'll need the following directive:</P>
<PRE>
Options +ExecCGI</PRE>
<P>which tells Apache that execution of CGI programs is permitted in this
directory.</P>
<P>
<HR>
<H1><A NAME="writing a cgi program">Writing a CGI program</A></H1>
<P>There are two main differences between ``regular'' programming, and CGI programming.</P>
<P>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:</P>
<PRE>
Content-type: text/html</PRE>
<P>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.</P>
<P>Apart from those two things, writing a CGI program will look a lot like any other
program that you might write.</P>
<P>
<H2><A NAME="your first cgi program">Your first CGI program</A></H2>
<P>The following is an example CGI program that prints one line to your browser.
Type in the following, save it to a file called <CODE>first.pl</CODE>, and put it in your
<CODE>cgi-bin</CODE> directory.</P>
<PRE>
#!/usr/bin/perl
print "Content-type: text/html\r\n\r\n";
print "Hello, World.";</PRE>
<P>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 <CODE>/usr/bin/perl</CODE>. 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.</P>
<P>If you open your favorite browser and tell it to get the address</P>
<PRE>
<A HREF="http://your.server.com/cgi-bin/first.pl">http://your.server.com/cgi-bin/first.pl</A></PRE>
<P>or wherever you put your file, you will see the one line <CODE>Hello, World.</CODE> 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.</P>
<P>
<HR>
<H1><A NAME="but it's still not working!">But it's still not working!</A></H1>
<P>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.</P>
<P>
<H2><A NAME="file permissions">File permissions</A></H2>
<P>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 ``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:</P>
<PRE>
chmod a+x first.pl</PRE>
<P>Also, if your program reads from, or writes to, any other files, those files
will need to have the correct permissions to permit this.</P>
<P>
<H2><A NAME="path information">Path information</A></H2>
<P>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.</P>
<P>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.</P>
<P>A common manifestation of this is the path to the script interpreter
(often <CODE>perl</CODE>) indicated in the first line of your CGI program, which will
look something like:</P>
<PRE>
#!/usr/bin/perl</PRE>
<P>Make sure that this is in fact the path to the interpreter.</P>
<P>
<H2><A NAME="syntax errors">Syntax errors</A></H2>
<P>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.</P>
<P>
<H2><A NAME="error logs">Error logs</A></H2>
<P>The error logs are your friend. Anything that goes wrong generatesa 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.</P>
<P>
<HR>
<H1><A NAME="what's going on behind the scenes">What's going on behind the scenes?</A></H1>
<P>As you become more advanced in CGI programming, it will become useful to understand
more about what's happening behind the scenes. Specifically, how the browser and
server communicate with one another. Because although it's all very well
to write a program that prints ``Hello, World.'', it's not particularly useful.</P>
<P>
<H2><A NAME="environment variables">Environment variables</A></H2>
<P>Environment variables are values that float around you as you use your
computer. They are useful things like your path (where the computer searches
for a the actual file implementing a command when you type it), your username,
your terminal type, and so on. For a full list of your normal, every day
environment variables, type <CODE>env</CODE> at a command prompt.</P>
<P>During the CGI transaction, the server and the browser also set environment
variables, so that they can communicate with one another. These are things
like the browser type (Netscape, IE, Lynx), the server type (Apache, IIS,
WebSite), the name of the CGI program that is being run, and so on.</P>
<P>These variables are available to the CGI programmer, and are half of the
story of the client-server communication. The complete list of required
variables is at <A HREF="http://hoohoo.ncsa.uiuc.edu/cgi/env.html">http://hoohoo.ncsa.uiuc.edu/cgi/env.html</A></P>
<P>This simple Perl CGI program will display all of the environment variables that
are being passed around. Note that some variables are required, while others
are optional, so you may see some variables listed that were not in the
official list.</P>
<PRE>
#!/usr/bin/perl
print "Content-type: text/html\n\n";
foreach $key (keys %ENV) {
print "$key --> $ENV{$key}<br>";
}</PRE>
<P>
<H2><A NAME="stdin and stdout">STDIN and STDOUT</A></H2>
<P>Other communication between the server and the client happens over standard
input (<CODE>STDIN</CODE>) and standard output (<CODE>STDOUT</CODE>). In normal everyday context,
<CODE>STDIN</CODE> means the keyboard, or a file that a program is given to act on,
and <CODE>STDOUT</CODE> usually means the console or screen.</P>
<P>When you <CODE>POST</CODE> a web form to a CGI program, the data in that form is
bundled up into a special format and gets delivered to your CGI program
over <CODE>STDIN</CODE>. The program then can process that data as though it wsa coming
in from the keyboard, or from a file</P>
<P>The ``special format'' is very simple. A field name and its value are joined
together with an equals (=) sign, and pairs of values are joined together
with an ampersand (&). Inconvenient characters like spaces, ampersands, and
equals signs, are converted into their hex equivalent so that they don't gum
up the works. The whole data string might look something like:</P>
<PRE>
name=Rich%20Bowen&city=Lexington&state=KY&sidekick=Squirrel%20Monkey</PRE>
<P>You'll sometimes also see this type of string appended to the a URL. When
that is done, the server puts that string into the environment variable
called <CODE>QUERY_STRING</CODE>. That's called a <CODE>GET</CODE> request. Your HTML form
specifies whether a <CODE>GET</CODE> or a <CODE>POST</CODE> is used to deliver the data, by
setting the <CODE>METHOD</CODE> attribute in the <CODE>FORM</CODE> tag.</P>
<P>Your program is then responsible for splitting that string up into useful
information. Fortunately, there are libraries and modules available to
help you process this data, as well as handle other of the aspects of
your CGI program.</P>
<P>
<HR>
<H1><A NAME="cgi modules/libraries">CGI modules/libraries</A></H1>
<P>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.</P>
<P>If you're writing CGI programs in Perl, modules are available on CPAN
(http://www.cpan.org/). The most popular module for this purpose is
CGI.pm. You might also consider CGI::Lite, which implements a
minimal set of functionality, which is all you need in most programs.</P>
<P>If you're writing CGI programs in C, there are a variety of options.
One of these is the CGIC library, from <A HREF="http://www.boutell.com/cgic/">http://www.boutell.com/cgic/</A></P>
<P>
<HR>
<H1><A NAME="for more information">For more information</A></H1>
<P>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 <A HREF="http://www.hwg.org/lists/hwg-servers/">http://www.hwg.org/lists/hwg-servers/</A></P>
<P>And, of course, as I mentioned above, you should probably read the CGI
specification, which you can find at
<A HREF="http://hoohoo.ncsa.uiuc.edu/cgi/interface.html">http://hoohoo.ncsa.uiuc.edu/cgi/interface.html</A></P>
<P>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.</P>
</BODY>
</HTML>