httpd-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sl...@locus.apache.org
Subject cvs commit: httpd-docs-1.3/htdocs/manual/howto cgi.html
Date Sun, 12 Nov 2000 22:46:49 GMT
slive       00/11/12 14:46:49

  Modified:    htdocs/manual/howto cgi.html
  Log:
  Some updates to the cgi tutorial.
  Notable changes:
  
  - Change "CGI Program" to "CGI Script" in most locations.  This is
  less accurate overall, but is the canonical way of saying it in the
  Apache documentation.  I hated making this change, and could be easily
  convinced to change it back.
  
  - Changed the statement on when CGI might be used outside ScriptAlias'ed
  directories.
  
  - Changed the section at the top of "it's still not working" to
  address the three most common initial problems as reported on
  the newsgroups.
  
  - Added a brief discussion of suexec to the "permissions problems" section.
  
  - Added a few pointers in the environment variable section.
  
  - Added a pointer to the CGI RFC project near the bottom.
  
  Things still to be done:
  
  - Add a Related Directives / Related Modules section at the top.
  
  - Link it up from mod_cgi and manual/index.html.
  
  Rich, I hope I'm not stepping on your toes with these changes.  Please
  let me know if you object to anything here, and I'll be happy to back
  it out.
  
  Revision  Changes    Path
  1.3       +137 -93   httpd-docs-1.3/htdocs/manual/howto/cgi.html
  
  Index: cgi.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/howto/cgi.html,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- cgi.html	2000/11/12 21:39:34	1.2
  +++ cgi.html	2000/11/12 22:46:49	1.3
  @@ -1,8 +1,7 @@
   <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
   <html>
   <head>
  -<meta name="generator" content="HTML Tidy, see www.w3.org">
  -<title>Dynamic Content with CGI</title>
  +<title>Apache Tutorial: Dynamic Content with CGI</title>
   <link rev="made" href="mailto:rbowen@rcbowen.com">
   </head>
   <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  @@ -19,16 +18,14 @@
   CGI</a></li>
   
   <li><a href="#configuring apache to permit cgi">Configuring Apache to
  -permit CGI</a></li>
  +permit CGI</a>
   
  -<li style="list-style: none">
   <ul>
   <li><a href="#scriptalias">ScriptAlias</a></li>
   
   <li><a href="#cgi outside of scriptalias directories">CGI outside of
  -ScriptAlias directories</a></li>
  +ScriptAlias directories</a>
   
  -<li style="list-style: none">
   <ul>
   <li><a href=
   "#explicitly using options to permit cgi execution">Explicitly using
  @@ -40,18 +37,16 @@
   </ul>
   </li>
   
  -<li><a href="#writing a cgi program">Writing a CGI program</a></li>
  +<li><a href="#writing a cgi script">Writing a CGI script</a>
   
  -<li style="list-style: none">
   <ul>
  -<li><a href="#your first cgi program">Your first CGI program</a></li>
  +<li><a href="#your first cgi script">Your first CGI script</a></li>
   </ul>
   </li>
   
   <li><a href="#but it's still not working!">But it's still not
  -working!</a></li>
  +working!</a>
   
  -<li style="list-style: none">
   <ul>
   <li><a href="#file permissions">File permissions</a></li>
   
  @@ -64,9 +59,8 @@
   </li>
   
   <li><a href="#what's going on behind the scenes">What's going on behind
  -the scenes?</a></li>
  +the scenes?</a>
   
  -<li style="list-style: none">
   <ul>
   <li><a href="#environment variables">Environment variables</a></li>
   
  @@ -81,34 +75,31 @@
   
   <!-- INDEX END -->
   <hr>
  -<h1><a name="dynamic content with cgi">Dynamic Content with
  -CGI</a></h1>
  +<h2><a name="dynamic content with cgi">Dynamic Content with
  +CGI</a></h2>
   
  -<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>The CGI (Common Gateway Interface) defines a way for a web server
  +to interact with external content-generating programs.  It 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 scripts.</p>
   
   <hr>
  -<h1><a name="configuring apache to permit cgi">Configuring Apache to
  -permit CGI</a></h1>
  +<h2><a name="configuring apache to permit cgi">Configuring Apache to
  +permit CGI</a></h2>
   
  -<p>In order to get your CGI programs to work properly, you'll need to
  +<p>In order to get your CGI scripts 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>
  +<h3><a name="scriptalias">ScriptAlias</a></h3>
   
   <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
  +particular directory is set aside for CGI scripts. Apache will assume
  +that every file in this directory is a CGI script, 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>
  +<p>The <code>ScriptAlias</code> directive looks like:</p>
   
   <pre>
           ScriptAlias /cgi-bin/ /usr/local/apache/cgi-bin/
  @@ -123,11 +114,11 @@
   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
  +that URL prefix will be considered a CGI script. 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>
  +script.</p>
   
   <p>For example, if the URL
   <code>http://dev.rcbowen.com/cgi-bin/test.pl</code> is requested,
  @@ -136,15 +127,19 @@
   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 directories</a></h2>
  +<h3><a name="cgi outside of scriptalias directories">CGI outside of
  +ScriptAlias directories</a></h3>
   
  -<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>CGI scripts are often restricted to <code>ScriptAlias</code>'ed
  +directories for security reasons.  In this way, administrators can
  +tightly control who is allowed to use CGI scripts.  However, if the
  +proper security precautions are taken, there is no reason why
  +CGI scripts cannot be run from arbitrary directories.  For example,
  +you may wish to let users have web content in their home directories
  +with the <code>UserDir</code> directive. If they want to have their
  +own CGI scripts, but don't have access to the main
  +<code>cgi-bin</code> directory, they will need to be able to run CGI
  +scripts elsewhere.</p>
   
   <h3><a name=
   "explicitly using options to permit cgi execution">Explicitly using
  @@ -162,7 +157,9 @@
   
   <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>
  +The following <code>AddHandler</code> directive tells the server
  +to treat all files with the <code>cgi</code> or <code>pl</code>
  +extension as CGI scripts:</p>
   
   <pre>
        AddHandler cgi-script cgi pl
  @@ -192,16 +189,16 @@
           Options +ExecCGI
   </pre>
   
  -<p>which tells Apache that execution of CGI programs is permitted in
  +<p>which tells Apache that execution of CGI scripts is permitted in
   this directory.</p>
   
   <hr>
  -<h1><a name="writing a cgi program">Writing a CGI program</a></h1>
  +<h2><a name="writing a cgi script">Writing a CGI script</a></h2>
   
   <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
  +<p>First, all output from your CGI script must be preceded 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>
   
  @@ -211,15 +208,15 @@
   
   <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
  +but occasionally you might write a CGI script 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
  +<p>Apart from those two things, writing a CGI script 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>
  +<h3><a name="your first cgi script">Your first CGI script</a></h3>
   
  -<p>The following is an example CGI program that prints one line to your
  +<p>The following is an example CGI script 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>
  @@ -243,8 +240,7 @@
   <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>
  +        http://www.example.com/cgi-bin/first.pl</a>
   </pre>
   
   <p>or wherever you put your file, you will see the one line
  @@ -253,16 +249,40 @@
   getting just about anything working.</p>
   
   <hr>
  -<h1><a name="but it's still not working!">But it's still not
  -working!</a></h1>
  +<h2><a name="but it's still not working!">But it's still not
  +working!</a></h2>
   
  -<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>There are four basic things that you may see in your browser when
  +you try to access your CGI script from the web:</p>
   
  -<h2><a name="file permissions">File permissions</a></h2>
  +<dl>
  +<dt>The output of your CGI script</dt>
  +<dd>Great!  That means everything worked fine.<br><br></dd>
  +
  +<dt>The source code of your CGI script</dt> 
  +<dd>That means that you have not properly configured Apache to process
  +your CGI script.  Reread the section on <a
  +href="#configuring%20apache%20to%20permit%20cgi">configuring
  +Apache</a> and try to find what you missed.<br><br></dd>
  +
  +<dt>A message starting with "Forbidden"</dt> <dd>That means that there
  +is a permissions problem.  Check the <a href="#error%20logs">Apache
  +error log</a> and the section below on <a
  +href="#file%20permissions">file permissions</a>.<br><br></dd>
  +
  +<dt>A message saying "Internal Server Error"</dt> <dd>If you check the
  +<a href="#error%20logs">Apache error log</a>, you will probably find
  +that it says "Premature end of script headers", possibly along with an
  +error message generated by your CGI script.  In this case, you will
  +want to check each of the below sections to see what might be preventing
  +your CGI script from emitting the proper HTTP headers.</dt>
  +</dl>
   
  +
  +<h3><a name="file permissions">File permissions</a></h3>
  +
   <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
  +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
  @@ -275,23 +295,32 @@
   <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>The exception to this is when the server is configured to use <a
  +href="../suexec.html">suexec</a>.  This program allows CGI scripts to
  +be run under different user permissions, depending on which virtual
  +host or user home directory they are located in.  Suexec has very
  +strict permission checking, and any failure in that checking will
  +result in your CGI scripts failing with an "Internal Server Error".
  +In this case, you will need to check the suexec log file to see what
  +specific security check is failing.</p>
   
  -<h2><a name="path information">Path information</a></h2>
  +<h3><a name="path information">Path information</a></h3>
   
   <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
  +<p>When a script runs through the web server as a CGI script, it does
  +not have that path. Any programs that you invoke in your CGI script
   (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>
  +CGI script.</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>
  +script, which will look something like:</p>
   
   <pre>
        #!/usr/bin/perl
  @@ -299,17 +328,17 @@
   
   <p>Make sure that this is in fact the path to the interpreter.</p>
   
  -<h2><a name="syntax errors">Syntax errors</a></h2>
  +<h3><a name="syntax errors">Syntax errors</a></h3>
   
  -<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
  +<p>Most of the time when a CGI script fails, it's because of a problem
  +with the script 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>
  +Always attempt to run your script from the command line before you
  +test if via a browser. This will eliminate most of your problems.</p>
   
  -<h2><a name="error logs">Error logs</a></h2>
  +<h3><a name="error logs">Error logs</a></h3>
   
  -<p>The error logs are your friend. Anything that goes wrong generatesa
  +<p>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
  @@ -317,16 +346,16 @@
   problems are quickly identified, and quickly solved.</p>
   
   <hr>
  -<h1><a name="what's going on behind the scenes">What's going on behind
  -the scenes?</a></h1>
  +<h2><a name="what's going on behind the scenes">What's going on behind
  +the scenes?</a></h2>
   
   <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
  +Because although it's all very well to write a script that prints
   ``Hello, World.'', it's not particularly useful.</p>
   
  -<h2><a name="environment variables">Environment variables</a></h2>
  +<h3><a name="environment variables">Environment variables</a></h3>
   
   <p>Environment variables are values that float around you as you use
   your computer. They are useful things like your path (where the
  @@ -338,7 +367,7 @@
   <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
  +type (Apache, IIS, WebSite), the name of the CGI script that is being
   run, and so on.</p>
   
   <p>These variables are available to the CGI programmer, and are half of
  @@ -346,10 +375,14 @@
   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>
  +<p>This simple Perl CGI script will display all of the environment
  +variables that are being passed around.  Two similar scripts are
  +included in the <code>cgi-bin</code> directory of the Apache
  +distribution. Note that some variables are required, while others are
  +optional, so you may see some variables listed that were not in the
  +official list.  In addition, Apache provides many different ways for
  +you to <a href="../env.html">add your own environment variables</a> to
  +the basic ones provided by default.</p>
   
   <pre>
        #!/usr/bin/perl
  @@ -359,7 +392,7 @@
        }
   </pre>
   
  -<h2><a name="stdin and stdout">STDIN and STDOUT</a></h2>
  +<h3><a name="stdin and stdout">STDIN and STDOUT</a></h3>
   
   <p>Other communication between the server and the client happens over
   standard input (<code>STDIN</code>) and standard output
  @@ -367,10 +400,10 @@
   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
  +<p>When you <code>POST</code> a web form to a CGI script, 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
  +your CGI script over <code>STDIN</code>. The script then can process
  +that data as though it was coming in from the keyboard, or from a
   file</p>
   
   <p>The ``special format'' is very simple. A field name and its value
  @@ -392,30 +425,30 @@
   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
  +<p>Your script 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>
  +aspects of your CGI script.</p>
   
   <hr>
  -<h1><a name="cgi modules/libraries">CGI modules/libraries</a></h1>
  +<h2><a name="cgi modules/libraries">CGI modules/libraries</a></h2>
   
  -<p>When you write CGI programs, you should consider using a code
  +<p>When you write CGI scripts, 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
  +<p>If you're writing CGI scripts 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>
  +scripts.</p>
   
  -<p>If you're writing CGI programs in C, there are a variety of options.
  +<p>If you're writing CGI scripts 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>
   
   <hr>
  -<h1><a name="for more information">For more information</a></h1>
  +<h2><a name="for more information">For more information</a></h2>
   
   <p>There are a large number of CGI resources on the web. You can
   discuss CGI problems with other users on the Usenet group
  @@ -424,16 +457,27 @@
   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>And, of course, you should probably read the CGI specification,
  +which has all the details on the operation of CGI scripts.  You can
  +find the original version at the <a href=
  +"http://hoohoo.ncsa.uiuc.edu/cgi/interface.html">NCSA</a> and there is
  +an updated draft at the <a
  +href="http://web.golux.com/coar/cgi/">Common Gateway Interface RFC
  +project</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
  +running, what language your CGI script was in, and, if possible, the
   offending code. This will make finding your problem much simpler.</p>
  +
  +<p>Note that questions about CGI problems should <strong>never</strong>
  +be posted to the Apache bug database unless you are sure you have found
  +a problem in the Apache source code.</p>
  +
  +<!--#include virtual="footer.html" -->
  +
   </body>
   </html>
   
  
  
  

Mime
View raw message