httpd-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject cvs commit: httpd-docs-1.3/htdocs/manual/howto cgi_HOWTO.html
Date Sun, 12 Nov 2000 13:15:52 GMT
rbowen      00/11/12 05:15:52

  Added:       htdocs/manual/howto cgi_HOWTO.html
  CGI tutorial. Initial contribution.
  Revision  Changes    Path
  1.1                  httpd-docs-1.3/htdocs/manual/howto/cgi_HOWTO.html
  Index: cgi_HOWTO.html
  <TITLE>Dynamic Content with CGI</TITLE>
  <LINK REV="made" HREF="">
  <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  <!--#include virtual="header.html" -->
  <H1 ALIGN="CENTER">Dynamic Content with CGI</H1>
  <A NAME="__index__"></A>
  <!-- INDEX BEGIN -->
  	<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
  		<LI><A HREF="#scriptalias">ScriptAlias</A></LI>
  		<LI><A HREF="#cgi outside of scriptalias directories">CGI outside of ScriptAlias
  			<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>
  	<LI><A HREF="#writing a cgi program">Writing a CGI program</A></LI>
  		<LI><A HREF="#your first cgi program">Your first CGI program</A></LI>
  	<LI><A HREF="#but it's still not working!">But it's still not working!</A></LI>
  		<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>
  	<LI><A HREF="#what's going on behind the scenes">What's going on behind the
  		<LI><A HREF="#environment variables">Environment variables</A></LI>
  		<LI><A HREF="#stdin and stdout">STDIN and STDOUT</A></LI>
  	<LI><A HREF="#cgi modules/libraries">CGI modules/libraries</A></LI>
  	<LI><A HREF="#for more information">For more information</A></LI>
  <!-- INDEX END -->
  <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=""></A></P>
  <H1><A NAME="configuring apache to permit cgi">Configuring Apache to permit
  <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>
  <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>
          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>
  The difference between <CODE>Alias</CODE> and <CODE>ScriptAlias</CODE>
  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
  <CODE>/usr/local/apache/cgi-bin/</CODE>, and should be treated as a CGI program.</P>
  <P>For example, if the URL <CODE></CODE>
is requested,
  Apache will attempt to execute the file <CODE>/usr/local/apache/cgi-bin/</CODE>
  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>
  <H2><A NAME="cgi outside of scriptalias directories">CGI outside of ScriptAlias
  <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
  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
  <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
          &lt;Directory /usr/local/apache/htdocs/somedir&gt;
                  Options +ExecCGI
  <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>
       AddHandler cgi-script cgi pl</PRE>
  <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>
          AllowOverride Options</PRE>
  <P>In the <CODE>.htaccess</CODE> file, you'll need the following directive:</P>
          Options +ExecCGI</PRE>
  <P>which tells Apache that execution of CGI programs is permitted in this
  <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>
          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>
  <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></CODE>, and put
it in your
  <CODE>cgi-bin</CODE> directory.</P>
          print &quot;Content-type: text/html\r\n\r\n&quot;;
          print &quot;Hello, World.&quot;;</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
  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>
          <A HREF=""></A></PRE>
  <P>or wherever you put your file, you will see the one line <CODE>Hello, World.</CODE>
  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>
  <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>
  <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>
          chmod a+x</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>
  <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
  look something like:</P>
  <P>Make sure that this is in fact the path to the interpreter.</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>
  <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>
  <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>
  <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=""></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>
       print &quot;Content-type: text/html\n\n&quot;;
       foreach $key (keys %ENV) {
            print &quot;$key --&gt; $ENV{$key}&lt;br&gt;&quot;;
  <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 (&amp;). 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>
  <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>
  <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>
  <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 
  ( The most popular module for this purpose is 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=""></A></P>
  <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=""></A></P>
  <P>And, of course, as I mentioned above, you should probably read the CGI
  specification, which you can find at 
  <A HREF=""></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>

View raw message