Make sure that the CGI tutorial answers

all the CGI FAQs that I commonly
see.


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@103298 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 104 insertions, 47 deletions

diff --git a/docs/manual/howto/cgi.xml b/docs/manual/howto/cgi.xml
index 70094cf37a..ebcb173919 100644
--- a/docs/manual/howto/cgi.xml
+++ b/docs/manual/howto/cgi.xml
@@ -71,7 +71,7 @@
       directive looks like:</p>
 
       <example>
-        ScriptAlias /cgi-bin/ /usr/local/apache/cgi-bin/
+        ScriptAlias /cgi-bin/ /usr/local/apache2/cgi-bin/
       </example>
 
       <p>The example shown is from your default <code>httpd.conf</code>
@@ -88,13 +88,13 @@
       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
+      the directory  <code>/usr/local/apache2/cgi-bin/</code>, and should be
       treated as a CGI program.</p>
 
       <p>For example, if the URL
       <code>http://www.example.com/cgi-bin/test.pl</code>
       is requested, Apache will attempt to execute the file 
-      <code>/usr/local/apache/cgi-bin/test.pl</code>
+      <code>/usr/local/apache2/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>
@@ -114,6 +114,14 @@
       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>There are two steps to allowing CGI execution in an arbitrary
+      directory.  First, the <code>cgi-script</code> handler must be
+      activated using the <directive
+      module="mod_mime">AddHandler</directive> or <directive
+      module="core">SetHandler</directive> directive.  Second,
+      <code>ExecCGI</code> must be specified in the <directive
+      module="core">Options</directive> directive.</p> 
     </section>
 
     <section id="options">
@@ -125,7 +133,7 @@
       directory:</p>
 
       <example>
-        &lt;Directory /usr/local/apache/htdocs/somedir&gt;<br />
+        &lt;Directory /usr/local/apache2/htdocs/somedir&gt;<br />
         <indent>
           Options +ExecCGI<br />
         </indent>
@@ -140,41 +148,49 @@
       programs:</p>
 
       <example>
-        AddHandler cgi-script cgi pl
+        AddHandler cgi-script .cgi .pl
       </example>
     </section>
 
     <section id="htaccess">
       <title>.htaccess files</title>
 
-      <p>A <a href="htaccess.html"><code>.htaccess</code> file</a> 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 
-      <directive module="core">AllowOverride</directive> 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>
+      <p>The <a href="htaccess.html"><code>.htaccess</code> tutorial</a>
+      shows how to activate CGI programs if you do not have
+      access to <code>httpd.conf</code>.</p>
+    </section>
+
+    <section id="userdir">
+      <title>User Directories</title>
+
+      <p>To allow CGI program execution for any file ending in
+      <code>.cgi</code> in users' directories, you can use the
+      following configuration.</p>
 
       <example>
-        AllowOverride Options
+      &lt;Directory /home/*/public_html&gt;<br/>
+      <indent>
+        Options +ExecCGI<br/>
+        AddHandler cgi-script .cgi<br/>
+      </indent>
+      &lt;/Directory&gt;
       </example>
 
-      <p>In the <code>.htaccess</code> file, you'll need the 
-      following directive:</p>
+      <p>If you wish designate a <code>cgi-bin</code> subdirectory of
+      a user's directory where everything will be treated as a CGI
+      program, you can use the following.</p>
 
       <example>
-        Options +ExecCGI
+      &lt;Directory /home/*/public_html/cgi-bin&gt;<br/>
+      <indent>
+        Options ExecCGI<br/>
+        SetHandler cgi-script<br/>
+      </indent>
+      &lt;/Directory&gt;
       </example>
 
-      <p>which tells Apache that execution of CGI programs is
-      permitted in this directory.</p>
     </section>
+
   </section>
 
   <section id="writing">
@@ -249,7 +265,9 @@
 
     <dl>
       <dt>The output of your CGI program</dt>
-      <dd>Great! That means everything worked fine.</dd>
+      <dd>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 <code>Content-Type</code> set in your CGI program.</dd>
 
       <dt>The source code of your CGI program or a "POST Method Not
       Allowed" message</dt>
@@ -293,30 +311,22 @@
       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 programs 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 programs 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>
     </section>
 
     <section id="pathinformation">
-      <title>Path information</title>
+      <title>Path information and environment</title>
 
       <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
+      thinking about it. For example, you have a <code>PATH</code>,
+      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 may not have the same <code>PATH</code>. Any programs that you
+      invoke in your CGI program (like <code>sendmail</code>, 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
@@ -329,17 +339,40 @@
 
       <p>Make sure that this is in fact the path to the
       interpreter.</p>
+
+      <p>In addition, if your CGI program depends on other <a
+      href="#env">environment variables</a>, you will need to
+      assure that those variables are passed by Apache.</p>
+
     </section>
 
     <section id="syntaxerrors">
-      <title>Syntax errors</title>
+      <title>Program errors</title>
 
       <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 eliminate most of your problems.</p>
+      the above two mistakes.  The first thing to do is to make
+      sure that your program runs from the command line before
+      testing it via the web server.  For example, try:</p>
+
+      <example>
+      cd /usr/local/apache2/cgi-bin<br/>
+      ./first.pl
+      </example>
+
+      <p>(Do not call the <code>perl</code> interpreter.  The shell
+      and Apache should find the interpreter using the <a
+      href="#pathinformation">path information</a> on the first line of
+      the script.)</p>
+
+      <p>The first thing you see written by your program should be
+      a set of HTTP headers, including the <code>Content-Type</code>,
+      followed by a blank line.  If you see anything else, Apache will
+      return the <code>Premature end of script headers</code> error if
+      you try to run it through the server. See <a
+      href="#writing">Writing a CGI program</a> above for more
+      details.</p>
     </section>
 
     <section id="errorlogs">
@@ -353,6 +386,30 @@
       error logs, and you'll find that almost all of your problems
       are quickly identified, and quickly solved.</p>
     </section>
+
+    <section id="suexec">
+      <title>Suexec</title>
+
+      <p>The <a href="../suexec.html">suexec</a> support program
+      allows CGI programs 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 programs
+      failing with <code>Premature end of script headers</code>.</p>
+
+      <p>To check if you are using suexec, run <code>apachectl
+      -V</code> and check for the location of <code>SUEXEC_BIN</code>.
+      If Apache finds an suexec binary there on startup, suexec will
+      be actived.</p>
+
+      <p>Unless you fully understand suexec, you should not be using it.
+      To disable suexec, simply remove (or rename) the <code>suexec</code>
+      binary pointed to by <code>SUEXEC_BIN</code> and then restart the
+      server.  If, after reading about <a href="../suexec.html">suexec</a>,
+      you still wish to use it, then run <code>suexec -V</code> to find
+      the location of the suexec log file, and use that log file to
+      find what policy you are violating.</p>
+    </section>
   </section>
 
   <section id="behindscenes">