docs/manual/misc/FAQ-F.html - httpd - Git at Google

 <!--#if expr="$FAQMASTER" -->
  <!--#set var="STANDALONE" value="" -->
  <!--#set var="INCLUDED" value="YES" -->
  <!--#if expr="$QUERY_STRING = TOC" -->
   <!--#set var="TOC" value="YES" -->
   <!--#set var="CONTENT" value="" -->
  <!--#else -->
   <!--#set var="TOC" value="" -->
   <!--#set var="CONTENT" value="YES" -->
  <!--#endif -->
 <!--#else -->
  <!--#set var="STANDALONE" value="YES" -->
  <!--#set var="INCLUDED" value="" -->
  <!--#set var="TOC" value="" -->
  <!--#set var="CONTENT" value="" -->
 <!--#endif -->
 <!--#if expr="$STANDALONE" -->
 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
 <HTML>
  <HEAD>
   <TITLE>Apache Server Frequently Asked Questions</TITLE>
  </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">Apache Server Frequently Asked Questions</H1>
   <P>
   $Revision: 1.2 $ ($Date: 1999/07/03 22:12:50 $)
   </P>
   <P>
   The latest version of this FAQ is always available from the main
   Apache web site, at
   &lt;<A
        HREF="http://www.apache.org/docs/misc/FAQ.html"
        REL="Help"
       ><SAMP>http://www.apache.org/docs/misc/FAQ.html</SAMP></A>&gt;.
   </P>
 <!-- Notes about changes:                                           -->
 <!--  - If adding a relative link to another part of the            -->
 <!--    documentation, *do* include the ".html" portion.  There's a -->
 <!--    good chance that the user will be reading the documentation -->
 <!--    on his own system, which may not be configured for          -->
 <!--    multiviews.                                                 -->
 <!--  - When adding items, make sure they're put in the right place -->
 <!--    - verify that the numbering matches up.                     -->
 <!--  - *Don't* use <PRE></PRE> blocks - they don't appear          -->
 <!--    correctly in a reliable way when this is converted to text  -->
 <!--    with Lynx.  Use <DL><DD><CODE>xxx<BR>xx</CODE></DD></DL>    -->
 <!--    blocks inside a <P></P> instead.  This is necessary to get  -->
 <!--    the horizontal and vertical indenting right.                -->
 <!--  - Don't forget to include an HR tag after the last /P tag     -->
 <!--    but before the /LI in an item.                              -->
   <P>
   If you are reading a text-only version of this FAQ, you may find numbers
   enclosed in brackets (such as &quot;[12]&quot;).  These refer to the list of
   reference URLs to be found at the end of the document.  These references
   do not appear, and are not needed, for the hypertext version.
   </P>
   <H2>The Questions</H2>
 <OL TYPE="A">
 <!--#endif -->
 <!--#if expr="$TOC || $STANDALONE" -->
  <LI VALUE="6"><STRONG>Dynamic Content (CGI and SSI)</STRONG>
   <OL>
    <LI><A HREF="#CGIoutsideScriptAlias">How do I enable CGI execution
         in directories other than the ScriptAlias?</A>
    </LI>
    <LI><A HREF="#premature-script-headers">What does it mean when my
         CGIs fail with &quot;<SAMP>Premature end of script
         headers</SAMP>&quot;?</A>
    </LI>
    <LI><A HREF="#POSTnotallowed">Why do I keep getting &quot;Method Not
         Allowed&quot; for form POST requests?</A>
    </LI>
    <LI><A HREF="#nph-scripts">How can I get my script's output without
         Apache buffering it?  Why doesn't my server push work?</A>
    </LI>
    <LI><A HREF="#cgi-spec">Where can I find the &quot;CGI
         specification&quot;?</A>
    </LI>
    <LI><A HREF="#fastcgi">Why isn't FastCGI included with Apache any
         more?</A>
    </LI>
    <LI><A HREF="#ssi-part-i">How do I enable SSI (parsed HTML)?</A>
    </LI>
    <LI><A HREF="#ssi-part-ii">Why don't my parsed files get cached?</A>
    </LI>
    <LI><A HREF="#ssi-part-iii">How can I have my script output parsed?</A>
    </LI>
    <LI><A HREF="#ssi-part-iv">SSIs don't work for VirtualHosts and/or
         user home directories</A>
    </LI>
    <LI><A HREF="#errordocssi">How can I use <CODE>ErrorDocument</CODE>
         and SSI to simplify customized error messages?</A>
    </LI>
    <LI><A HREF="#remote-user-var">Why is the environment variable
         <SAMP>REMOTE_USER</SAMP> not set?</A>
    </LI>
   </OL>
  </LI>
 <!--#endif -->
 <!--#if expr="$STANDALONE" -->
 </OL>

 <HR>

   <H2>The Answers</H2>
 <!--#endif -->
 <!--#if expr="! $TOC" -->

   <H3>F. Dynamic Content (CGI and SSI)</H3>
 <OL>

  <LI><A NAME="CGIoutsideScriptAlias">
       <STRONG>How do I enable CGI execution in directories other than
       the ScriptAlias?</STRONG>
      </A>
   <P>
   Apache recognizes all files in a directory named as a
   <A HREF="../mod/mod_alias.html#scriptalias"><SAMP>ScriptAlias</SAMP></A>
   as being eligible for execution rather than processing as normal
   documents.  This applies regardless of the file name, so scripts in a
   ScriptAlias directory don't need to be named
   &quot;<SAMP>*.cgi</SAMP>&quot; or &quot;<SAMP>*.pl</SAMP>&quot; or
   whatever.  In other words, <EM>all</EM> files in a ScriptAlias
   directory are scripts, as far as Apache is concerned.
   </P>
   <P>
   To persuade Apache to execute scripts in other locations, such as in
   directories where normal documents may also live, you must tell it how
   to recognize them - and also that it's okay to execute them.  For
   this, you need to use something like the
   <A HREF="../mod/mod_mime.html#addhandler"><SAMP>AddHandler</SAMP></A>
   directive.
   </P>
   <P>
   <OL>
    <LI>In an appropriate section of your server configuration files, add
     a line such as
     <P>
     <DL>
      <DD><CODE>AddHandler cgi-script .cgi</CODE>
      </DD>
     </DL>
     <P></P>
     <P>
     The server will then recognize that all files in that location (and
     its logical descendants) that end in &quot;<SAMP>.cgi</SAMP>&quot;
     are script files, not documents.
     </P>
    </LI>
    <LI>Make sure that the directory location is covered by an
     <A HREF="../mod/core.html#options"><SAMP>Options</SAMP></A>
     declaration that includes the <SAMP>ExecCGI</SAMP> option.
    </LI>
   </OL>
   <P></P>
   <P>
   In some situations, you might not want to actually
   allow all files named &quot;<SAMP>*.cgi</SAMP>&quot; to be executable.
   Perhaps all you want is to enable a particular file in a normal directory to
   be executable. This can be alternatively accomplished
   <EM>via</EM> <A HREF="../mod/mod_rewrite.html"><SAMP>mod_rewrite</SAMP></A>
   and the following steps:
   </P>
   <P>
   <OL>
    <LI>Locally add to the corresponding <SAMP>.htaccess</SAMP> file a ruleset
     similar to this one:
     <P>
     <DL>
      <DD><CODE>RewriteEngine on
       <BR>
       RewriteBase   /~foo/bar/
       <BR>
       RewriteRule   ^quux\.cgi$  -  [T=application/x-httpd-cgi]</CODE>
      </DD>
     </DL>
     <P></P>
    </LI>
    <LI>Make sure that the directory location is covered by an
     <A HREF="../mod/core.html#options"><SAMP>Options</SAMP></A>
     declaration that includes the <SAMP>ExecCGI</SAMP> and
     <SAMP>FollowSymLinks</SAMP> option.
    </LI>
   </OL>
   <P></P>
   <HR>
  </LI>

  <LI><A NAME="premature-script-headers">
       <STRONG>What does it mean when my CGIs fail with
       &quot;<SAMP>Premature end of script headers</SAMP>&quot;?</STRONG>
      </A>
   <P>
   It means just what it says: the server was expecting a complete set of
   HTTP headers (one or more followed by a blank line), and didn't get
   them.
   </P>
   <P>
   The most common cause of this problem is the script dying before
   sending the complete set of headers, or possibly any at all, to the
   server.  To see if this is the case, try running the script standalone
   from an interactive session, rather than as a script under the server.
   If you get error messages, this is almost certainly the cause of the
   &quot;premature end of script headers&quot; message.  Even if the CGI
   runs fine from the command line, remember that the environment and
   permissions may be different when running under the web server.  The
   CGI can only access resources allowed for the <A
   HREF="../mod/core.html#user"><CODE>User</CODE></A> and
   <A HREF="../mod/core.html#group"><CODE>Group</CODE></A> specified in
   your Apache configuration.  In addition, the environment will not be
   the same as the one provided on the command line, but it can be
   adjusted using the directives provided by <A
   HREF="../mod/mod_env.html">mod_env</A>.
   </P>
   <P>
   The second most common cause of this (aside from people not
   outputting the required headers at all) is a result of an interaction
   with Perl's output buffering.  To make Perl flush its buffers
   after each output statement, insert the following statements around
   the <CODE>print</CODE> or <CODE>write</CODE> statements that send your
   HTTP headers:
   </P>
   <P>
   <DL>
    <DD><CODE>{<BR>
     &nbsp;local ($oldbar) = $|;<BR>
     &nbsp;$cfh = select (STDOUT);<BR>
     &nbsp;$| = 1;<BR>
     &nbsp;#<BR>
     &nbsp;# print your HTTP headers here<BR>
     &nbsp;#<BR>
     &nbsp;$| = $oldbar;<BR>
     &nbsp;select ($cfh);<BR>
     }</CODE>
    </DD>
   </DL>
   <P></P>
   <P>
   This is generally only necessary when you are calling external
   programs from your script that send output to stdout, or if there will
   be a long delay between the time the headers are sent and the actual
   content starts being emitted.  To maximize performance, you should
   turn buffer-flushing back <EM>off</EM> (with <CODE>$| = 0</CODE> or the
   equivalent) after the statements that send the headers, as displayed
   above.
   </P>
   <P>
   If your script isn't written in Perl, do the equivalent thing for
   whatever language you <EM>are</EM> using (<EM>e.g.</EM>, for C, call
   <CODE>fflush()</CODE> after writing the headers).
   </P>
   <P>
   Another cause for the &quot;premature end of script headers&quot;
   message are the RLimitCPU and RLimitMEM directives. You may
   get the message if the CGI script was killed due to a
   resource limit.
   </P>
   <P>
   In addition, a configuration problem in <A
   HREF="../suexec.html">suEXEC</A>, mod_perl, or another third party
   module can often interfere with the execution of your CGI and cause
   the &quot;premature end of script headers&quot; message.
   </P>
   <HR>
  </LI>

  <LI><A NAME="POSTnotallowed">
       <STRONG>Why do I keep getting &quot;Method Not Allowed&quot; for
       form POST requests?</STRONG>
      </A>
   <P>
   This is almost always due to Apache not being configured to treat the
   file you are trying to POST to as a CGI script.  You can not POST
   to a normal HTML file; the operation has no meaning.  See the FAQ
   entry on <A HREF="#CGIoutsideScriptAlias">CGIs outside ScriptAliased
   directories</A> for details on how to configure Apache to treat the
   file in question as a CGI.
   </P>
   <HR>
  </LI>

  <LI><A NAME="nph-scripts">
       <STRONG>How can I get my script's output without Apache buffering
       it?  Why doesn't my server push work?</STRONG>
      </A>
   <P>
   As of Apache 1.3, CGI scripts are essentially not buffered.  Every time
   your script does a "flush" to output data, that data gets relayed on to
   the client.  Some scripting languages, for example Perl, have their own
   buffering for output - this can be disabled by setting the <CODE>$|</CODE>
   special variable to 1.  Of course this does increase the overall number
   of packets being transmitted, which can result in a sense of slowness for
   the end user.
   </P>
   <P>Prior to 1.3, you needed to use "nph-" scripts to accomplish
   non-buffering.  Today, the only difference between nph scripts and
   normal scripts is that nph scripts require the full HTTP headers to
   be sent.
   </P>
   <HR>
  </LI>

  <LI><A NAME="cgi-spec">
       <STRONG>Where can I find the &quot;CGI specification&quot;?</STRONG>
      </A>
   <P>
   The Common Gateway Interface (CGI) specification can be found at
   the original NCSA site
   &lt;<A HREF="http://hoohoo.ncsa.uiuc.edu/cgi/interface.html">
   <SAMP>http://hoohoo.ncsa.uiuc.edu/cgi/interface.html</SAMP></A>&gt;.
   This version hasn't been updated since 1995, and there have been
   some efforts to update it.
   </P>
   <P>
   A new draft is being worked on with the intent of making it an informational
   RFC; you can find out more about this project at
   &lt;<A HREF="http://web.golux.com/coar/cgi/"
       ><SAMP>http://web.golux.com/coar/cgi/</SAMP></A>&gt;.
   </P>
   <HR>
  </LI>

  <LI><A NAME="fastcgi">
       <STRONG>Why isn't FastCGI included with Apache any more?</STRONG>
      </A>
   <P>
   The simple answer is that it was becoming too difficult to keep the
   version being included with Apache synchronized with the master copy
   at the
   <A HREF="http://www.fastcgi.com/"
   >FastCGI web site</A>.  When a new version of Apache was released, the
   version of the FastCGI module included with it would soon be out of date.
   </P>
   <P>
   You can still obtain the FastCGI module for Apache from the master
   FastCGI web site.
   </P>
   <HR>
  </LI>

  <LI><A NAME="ssi-part-i">
       <STRONG>How do I enable SSI (parsed HTML)?</STRONG>
      </A>
   <P>
   SSI (an acronym for Server-Side Include) directives allow static HTML
   documents to be enhanced at run-time (<EM>e.g.</EM>, when delivered to
   a client by Apache).  The format of SSI directives is covered
   in the <A HREF="../mod/mod_include.html">mod_include manual</A>;
   suffice it to say that Apache supports not only SSI but
   xSSI (eXtended SSI) directives.
   </P>
   <P>
   Processing a document at run-time is called <EM>parsing</EM> it; hence
   the term &quot;parsed HTML&quot; sometimes used for documents that
   contain SSI instructions.  Parsing tends to be <EM>extremely</EM>
   resource-consumptive, and is not enabled by default.  It can also
   interfere with the cachability of your documents, which can put a
   further load on your server.  (see the
   <A HREF="#ssi-part-ii">next question</A> for more information about this.)
   </P>
   <P>
   To enable SSI processing, you need to
   </P>
   <UL>
    <LI>Build your server with the
     <A HREF="../mod/mod_include.html"><SAMP>mod_include</SAMP></A>
     module.  This is normally compiled in by default.
    </LI>
    <LI>Make sure your server configuration files have an
     <A HREF="../mod/core.html#options"><SAMP>Options</SAMP></A>
     directive which permits <SAMP>Includes</SAMP>.
    </LI>
    <LI>Make sure that the directory where you want the SSI documents to
     live is covered by the &quot;server-parsed&quot; content handler,
     either explicitly or in some ancestral location.  That can be done
     with the following
     <A HREF="../mod/mod_mime.html#addhandler"><SAMP>AddHandler</SAMP></A>
     directive:
     <P>
     <DL>
      <DD><CODE>AddHandler server-parsed .shtml</CODE>
      </DD>
     </DL>
     <P></P>
     <P>
     This indicates that all files ending in &quot;.shtml&quot; in that
     location (or its descendants) should be parsed.  Note that using
     &quot;.html&quot; will cause all normal HTML files to be parsed,
     which may put an inordinate load on your server.
     </P>
    </LI>
   </UL>
   <P>
   For additional information, see the <CITE>Apache Week</CITE> article on
   <A HREF="http://www.apacheweek.com/features/ssi" REL="Help"
   ><CITE>Using Server Side Includes</CITE></A>.
   </P>
   <HR>
  </LI>

  <LI><A NAME="ssi-part-ii">
       <STRONG>Why don't my parsed files get cached?</STRONG>
      </A>
   <P>
   Since the server is performing run-time processing of your SSI
   directives, which may change the content shipped to the client, it
   can't know at the time it starts parsing what the final size of the
   result will be, or whether the parsed result will always be the same.
   This means that it can't generate <SAMP>Content-Length</SAMP> or
   <SAMP>Last-Modified</SAMP> headers.  Caches commonly work by comparing
   the <SAMP>Last-Modified</SAMP> of what's in the cache with that being
   delivered by the server.  Since the server isn't sending that header
   for a parsed document, whatever's doing the caching can't tell whether
   the document has changed or not - and so fetches it again to be on the
   safe side.
   </P>
   <P>
   You can work around this in some cases by causing an
   <SAMP>Expires</SAMP> header to be generated.  (See the
   <A HREF="../mod/mod_expires.html" REL="Help"><SAMP>mod_expires</SAMP></A>
   documentation for more details.)  Another possibility is to use the
   <A HREF="../mod/mod_include.html#xbithack" REL="Help"
   ><SAMP>XBitHack Full</SAMP></A>
   mechanism, which tells Apache to send (under certain circumstances
   detailed in the XBitHack directive description) a
   <SAMP>Last-Modified</SAMP> header based upon the last modification
   time of the file being parsed.  Note that this may actually be lying
   to the client if the parsed file doesn't change but the SSI-inserted
   content does; if the included content changes often, this can result
   in stale copies being cached.
   </P>
   <HR>
  </LI>

  <LI><A NAME="ssi-part-iii">
       <STRONG>How can I have my script output parsed?</STRONG>
      </A>
   <P>
   So you want to include SSI directives in the output from your CGI
   script, but can't figure out how to do it?
   The short answer is &quot;you can't.&quot;  This is potentially
   a security liability and, more importantly, it can not be cleanly
   implemented under the current server API.  The best workaround
   is for your script itself to do what the SSIs would be doing.
   After all, it's generating the rest of the content.
   </P>
   <P>
   This is a feature The Apache Group hopes to add in the next major
   release after 1.3.
   </P>
   <HR>
  </LI>

  <LI><A NAME="ssi-part-iv">
       <STRONG>SSIs don't work for VirtualHosts and/or
         user home directories.</STRONG>
      </A>
   <P>
   This is almost always due to having some setting in your config file that
   sets "Options Includes" or some other setting for your DocumentRoot
   but not for other directories.  If you set it inside a Directory
   section, then that setting will only apply to that directory.
   </P>
   <HR>
  </LI>

  <LI><A NAME="errordocssi">
       <STRONG>How can I use <CODE>ErrorDocument</CODE>
       and SSI to simplify customized error messages?</STRONG>
      </A>
   <P>
   Have a look at <A HREF="custom_errordocs.html">this document</A>.
   It shows in example form how you can a combination of XSSI and
   negotiation to tailor a set of <CODE>ErrorDocument</CODE>s to your
   personal taste, and returning different internationalized error
   responses based on the client's native language.
   </P>
   <HR>
  </LI>

  <LI><A NAME="remote-user-var">
       <STRONG>Why is the environment variable
       <SAMP>REMOTE_USER</SAMP> not set?</STRONG>
      </A>
   <P>
   This variable is set and thus available in SSI or CGI scripts <STRONG>if and
   only if</STRONG> the requested document was protected by access
   authentication.  For an explanation on how to implement these restrictions,
   see
   <A HREF="http://www.apacheweek.com/"><CITE>Apache Week</CITE></A>'s
   articles on
   <A HREF="http://www.apacheweek.com/features/userauth"
   ><CITE>Using User Authentication</CITE></A>
   or
   <A HREF="http://www.apacheweek.com/features/dbmauth"
   ><CITE>DBM User Authentication</CITE></A>.
   </P>
   <P>
   Hint: When using a CGI script to receive the data of a HTML <SAMP>FORM</SAMP>
   notice that protecting the document containing the <SAMP>FORM</SAMP> is not
   sufficient to provide <SAMP>REMOTE_USER</SAMP> to the CGI script.  You have
   to protect the CGI script, too. Or alternatively only the CGI script (then
   authentication happens only after filling out the form).
   </P>
   <HR>
  </LI>

 </OL>
 <!--#endif -->
 <!--#if expr="$STANDALONE" -->
   <!-- Don't forget to add HR tags at the end of each list item.. -->

 <!--#include virtual="footer.html" -->
 </BODY>
 </HTML>
 <!--#endif -->
	<!--#if expr="$FAQMASTER" -->
	<!--#set var="STANDALONE" value="" -->
	<!--#set var="INCLUDED" value="YES" -->
	<!--#if expr="$QUERY_STRING = TOC" -->
	<!--#set var="TOC" value="YES" -->
	<!--#set var="CONTENT" value="" -->
	<!--#else -->
	<!--#set var="TOC" value="" -->
	<!--#set var="CONTENT" value="YES" -->
	<!--#endif -->
	<!--#else -->
	<!--#set var="STANDALONE" value="YES" -->
	<!--#set var="INCLUDED" value="" -->
	<!--#set var="TOC" value="" -->
	<!--#set var="CONTENT" value="" -->
	<!--#endif -->
	<!--#if expr="$STANDALONE" -->
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
	<HTML>
	<HEAD>
	<TITLE>Apache Server Frequently Asked Questions</TITLE>
	</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">Apache Server Frequently Asked Questions</H1>
	<P>
	$Revision: 1.2 $ ($Date: 1999/07/03 22:12:50 $)
	</P>
	<P>
	The latest version of this FAQ is always available from the main
	Apache web site, at
	<<A
	HREF="http://www.apache.org/docs/misc/FAQ.html"
	REL="Help"
	><SAMP>http://www.apache.org/docs/misc/FAQ.html</SAMP></A>>.
	</P>
	<!-- Notes about changes: -->
	<!-- - If adding a relative link to another part of the -->
	<!-- documentation, do include the ".html" portion. There's a -->
	<!-- good chance that the user will be reading the documentation -->
	<!-- on his own system, which may not be configured for -->
	<!-- multiviews. -->
	<!-- - When adding items, make sure they're put in the right place -->
	<!-- - verify that the numbering matches up. -->
	<!-- - Don't use <PRE></PRE> blocks - they don't appear -->
	<!-- correctly in a reliable way when this is converted to text -->
	<!-- with Lynx. Use <DL><DD><CODE>xxx<BR>xx</CODE></DD></DL> -->
	<!-- blocks inside a <P></P> instead. This is necessary to get -->
	<!-- the horizontal and vertical indenting right. -->
	<!-- - Don't forget to include an HR tag after the last /P tag -->
	<!-- but before the /LI in an item. -->
	<P>
	If you are reading a text-only version of this FAQ, you may find numbers
	enclosed in brackets (such as "[12]"). These refer to the list of
	reference URLs to be found at the end of the document. These references
	do not appear, and are not needed, for the hypertext version.
	</P>
	<H2>The Questions</H2>
	<OL TYPE="A">
	<!--#endif -->
	<!--#if expr="$TOC \|\| $STANDALONE" -->
	<LI VALUE="6"><STRONG>Dynamic Content (CGI and SSI)</STRONG>
	<OL>
	<LI><A HREF="#CGIoutsideScriptAlias">How do I enable CGI execution
	in directories other than the ScriptAlias?</A>
	</LI>
	<LI><A HREF="#premature-script-headers">What does it mean when my
	CGIs fail with "<SAMP>Premature end of script
	headers</SAMP>"?</A>
	</LI>
	<LI><A HREF="#POSTnotallowed">Why do I keep getting "Method Not
	Allowed" for form POST requests?</A>
	</LI>
	<LI><A HREF="#nph-scripts">How can I get my script's output without
	Apache buffering it? Why doesn't my server push work?</A>
	</LI>
	<LI><A HREF="#cgi-spec">Where can I find the "CGI
	specification"?</A>
	</LI>
	<LI><A HREF="#fastcgi">Why isn't FastCGI included with Apache any
	more?</A>
	</LI>
	<LI><A HREF="#ssi-part-i">How do I enable SSI (parsed HTML)?</A>
	</LI>
	<LI><A HREF="#ssi-part-ii">Why don't my parsed files get cached?</A>
	</LI>
	<LI><A HREF="#ssi-part-iii">How can I have my script output parsed?</A>
	</LI>
	<LI><A HREF="#ssi-part-iv">SSIs don't work for VirtualHosts and/or
	user home directories</A>
	</LI>
	<LI><A HREF="#errordocssi">How can I use <CODE>ErrorDocument</CODE>
	and SSI to simplify customized error messages?</A>
	</LI>
	<LI><A HREF="#remote-user-var">Why is the environment variable
	<SAMP>REMOTE_USER</SAMP> not set?</A>
	</LI>
	</OL>
	</LI>
	<!--#endif -->
	<!--#if expr="$STANDALONE" -->
	</OL>

	<HR>

	<H2>The Answers</H2>
	<!--#endif -->
	<!--#if expr="! $TOC" -->

	<H3>F. Dynamic Content (CGI and SSI)</H3>
	<OL>

	<LI><A NAME="CGIoutsideScriptAlias">
	<STRONG>How do I enable CGI execution in directories other than
	the ScriptAlias?</STRONG>
	</A>
	<P>
	Apache recognizes all files in a directory named as a
	<A HREF="../mod/mod_alias.html#scriptalias"><SAMP>ScriptAlias</SAMP></A>
	as being eligible for execution rather than processing as normal
	documents. This applies regardless of the file name, so scripts in a
	ScriptAlias directory don't need to be named
	"<SAMP>.cgi</SAMP>" or "<SAMP>.pl</SAMP>" or
	whatever. In other words, <EM>all</EM> files in a ScriptAlias
	directory are scripts, as far as Apache is concerned.
	</P>
	<P>
	To persuade Apache to execute scripts in other locations, such as in
	directories where normal documents may also live, you must tell it how
	to recognize them - and also that it's okay to execute them. For
	this, you need to use something like the
	<A HREF="../mod/mod_mime.html#addhandler"><SAMP>AddHandler</SAMP></A>
	directive.
	</P>
	<P>
	<OL>
	<LI>In an appropriate section of your server configuration files, add
	a line such as
	<P>
	<DL>
	<DD><CODE>AddHandler cgi-script .cgi</CODE>
	</DD>
	</DL>
	<P></P>
	<P>
	The server will then recognize that all files in that location (and
	its logical descendants) that end in "<SAMP>.cgi</SAMP>"
	are script files, not documents.
	</P>
	</LI>
	<LI>Make sure that the directory location is covered by an
	<A HREF="../mod/core.html#options"><SAMP>Options</SAMP></A>
	declaration that includes the <SAMP>ExecCGI</SAMP> option.
	</LI>
	</OL>
	<P></P>
	<P>
	In some situations, you might not want to actually
	allow all files named "<SAMP>*.cgi</SAMP>" to be executable.
	Perhaps all you want is to enable a particular file in a normal directory to
	be executable. This can be alternatively accomplished
	<EM>via</EM> <A HREF="../mod/mod_rewrite.html"><SAMP>mod_rewrite</SAMP></A>
	and the following steps:
	</P>
	<P>
	<OL>
	<LI>Locally add to the corresponding <SAMP>.htaccess</SAMP> file a ruleset
	similar to this one:
	<P>
	<DL>
	<DD><CODE>RewriteEngine on
	<BR>
	RewriteBase /~foo/bar/
	<BR>
	RewriteRule ^quux\.cgi$ - [T=application/x-httpd-cgi]</CODE>
	</DD>
	</DL>
	<P></P>
	</LI>
	<LI>Make sure that the directory location is covered by an
	<A HREF="../mod/core.html#options"><SAMP>Options</SAMP></A>
	declaration that includes the <SAMP>ExecCGI</SAMP> and
	<SAMP>FollowSymLinks</SAMP> option.
	</LI>
	</OL>
	<P></P>
	<HR>
	</LI>

	<LI><A NAME="premature-script-headers">
	<STRONG>What does it mean when my CGIs fail with
	"<SAMP>Premature end of script headers</SAMP>"?</STRONG>
	</A>
	<P>
	It means just what it says: the server was expecting a complete set of
	HTTP headers (one or more followed by a blank line), and didn't get
	them.
	</P>
	<P>
	The most common cause of this problem is the script dying before
	sending the complete set of headers, or possibly any at all, to the
	server. To see if this is the case, try running the script standalone
	from an interactive session, rather than as a script under the server.
	If you get error messages, this is almost certainly the cause of the
	"premature end of script headers" message. Even if the CGI
	runs fine from the command line, remember that the environment and
	permissions may be different when running under the web server. The
	CGI can only access resources allowed for the <A
	HREF="../mod/core.html#user"><CODE>User</CODE></A> and
	<A HREF="../mod/core.html#group"><CODE>Group</CODE></A> specified in
	your Apache configuration. In addition, the environment will not be
	the same as the one provided on the command line, but it can be
	adjusted using the directives provided by <A
	HREF="../mod/mod_env.html">mod_env</A>.
	</P>
	<P>
	The second most common cause of this (aside from people not
	outputting the required headers at all) is a result of an interaction
	with Perl's output buffering. To make Perl flush its buffers
	after each output statement, insert the following statements around
	the <CODE>print</CODE> or <CODE>write</CODE> statements that send your
	HTTP headers:
	</P>
	<P>
	<DL>
	<DD><CODE>{<BR>
	local ($oldbar) = $\|;<BR>
	$cfh = select (STDOUT);<BR>
	$\| = 1;<BR>
	#<BR>
	# print your HTTP headers here<BR>
	#<BR>
	$\| = $oldbar;<BR>
	select ($cfh);<BR>
	}</CODE>
	</DD>
	</DL>
	<P></P>
	<P>
	This is generally only necessary when you are calling external
	programs from your script that send output to stdout, or if there will
	be a long delay between the time the headers are sent and the actual
	content starts being emitted. To maximize performance, you should
	turn buffer-flushing back <EM>off</EM> (with <CODE>$\| = 0</CODE> or the
	equivalent) after the statements that send the headers, as displayed
	above.
	</P>
	<P>
	If your script isn't written in Perl, do the equivalent thing for
	whatever language you <EM>are</EM> using (<EM>e.g.</EM>, for C, call
	<CODE>fflush()</CODE> after writing the headers).
	</P>
	<P>
	Another cause for the "premature end of script headers"
	message are the RLimitCPU and RLimitMEM directives. You may
	get the message if the CGI script was killed due to a
	resource limit.
	</P>
	<P>
	In addition, a configuration problem in <A
	HREF="../suexec.html">suEXEC</A>, mod_perl, or another third party
	module can often interfere with the execution of your CGI and cause
	the "premature end of script headers" message.
	</P>
	<HR>
	</LI>

	<LI><A NAME="POSTnotallowed">
	<STRONG>Why do I keep getting "Method Not Allowed" for
	form POST requests?</STRONG>
	</A>
	<P>
	This is almost always due to Apache not being configured to treat the
	file you are trying to POST to as a CGI script. You can not POST
	to a normal HTML file; the operation has no meaning. See the FAQ
	entry on <A HREF="#CGIoutsideScriptAlias">CGIs outside ScriptAliased
	directories</A> for details on how to configure Apache to treat the
	file in question as a CGI.
	</P>
	<HR>
	</LI>

	<LI><A NAME="nph-scripts">
	<STRONG>How can I get my script's output without Apache buffering
	it? Why doesn't my server push work?</STRONG>
	</A>
	<P>
	As of Apache 1.3, CGI scripts are essentially not buffered. Every time
	your script does a "flush" to output data, that data gets relayed on to
	the client. Some scripting languages, for example Perl, have their own
	buffering for output - this can be disabled by setting the <CODE>$\|</CODE>
	special variable to 1. Of course this does increase the overall number
	of packets being transmitted, which can result in a sense of slowness for
	the end user.
	</P>
	<P>Prior to 1.3, you needed to use "nph-" scripts to accomplish
	non-buffering. Today, the only difference between nph scripts and
	normal scripts is that nph scripts require the full HTTP headers to
	be sent.
	</P>
	<HR>
	</LI>

	<LI><A NAME="cgi-spec">
	<STRONG>Where can I find the "CGI specification"?</STRONG>
	</A>
	<P>
	The Common Gateway Interface (CGI) specification can be found at
	the original NCSA site
	<<A HREF="http://hoohoo.ncsa.uiuc.edu/cgi/interface.html">
	<SAMP>http://hoohoo.ncsa.uiuc.edu/cgi/interface.html</SAMP></A>>.
	This version hasn't been updated since 1995, and there have been
	some efforts to update it.
	</P>
	<P>
	A new draft is being worked on with the intent of making it an informational
	RFC; you can find out more about this project at
	<<A HREF="http://web.golux.com/coar/cgi/"
	><SAMP>http://web.golux.com/coar/cgi/</SAMP></A>>.
	</P>
	<HR>
	</LI>

	<LI><A NAME="fastcgi">
	<STRONG>Why isn't FastCGI included with Apache any more?</STRONG>
	</A>
	<P>
	The simple answer is that it was becoming too difficult to keep the
	version being included with Apache synchronized with the master copy
	at the
	<A HREF="http://www.fastcgi.com/"
	>FastCGI web site</A>. When a new version of Apache was released, the
	version of the FastCGI module included with it would soon be out of date.
	</P>
	<P>
	You can still obtain the FastCGI module for Apache from the master
	FastCGI web site.
	</P>
	<HR>
	</LI>

	<LI><A NAME="ssi-part-i">
	<STRONG>How do I enable SSI (parsed HTML)?</STRONG>
	</A>
	<P>
	SSI (an acronym for Server-Side Include) directives allow static HTML
	documents to be enhanced at run-time (<EM>e.g.</EM>, when delivered to
	a client by Apache). The format of SSI directives is covered
	in the <A HREF="../mod/mod_include.html">mod_include manual</A>;
	suffice it to say that Apache supports not only SSI but
	xSSI (eXtended SSI) directives.
	</P>
	<P>
	Processing a document at run-time is called <EM>parsing</EM> it; hence
	the term "parsed HTML" sometimes used for documents that
	contain SSI instructions. Parsing tends to be <EM>extremely</EM>
	resource-consumptive, and is not enabled by default. It can also
	interfere with the cachability of your documents, which can put a
	further load on your server. (see the
	<A HREF="#ssi-part-ii">next question</A> for more information about this.)
	</P>
	<P>
	To enable SSI processing, you need to
	</P>
	<UL>
	<LI>Build your server with the
	<A HREF="../mod/mod_include.html"><SAMP>mod_include</SAMP></A>
	module. This is normally compiled in by default.
	</LI>
	<LI>Make sure your server configuration files have an
	<A HREF="../mod/core.html#options"><SAMP>Options</SAMP></A>
	directive which permits <SAMP>Includes</SAMP>.
	</LI>
	<LI>Make sure that the directory where you want the SSI documents to
	live is covered by the "server-parsed" content handler,
	either explicitly or in some ancestral location. That can be done
	with the following
	<A HREF="../mod/mod_mime.html#addhandler"><SAMP>AddHandler</SAMP></A>
	directive:
	<P>
	<DL>
	<DD><CODE>AddHandler server-parsed .shtml</CODE>
	</DD>
	</DL>
	<P></P>
	<P>
	This indicates that all files ending in ".shtml" in that
	location (or its descendants) should be parsed. Note that using
	".html" will cause all normal HTML files to be parsed,
	which may put an inordinate load on your server.
	</P>
	</LI>
	</UL>
	<P>
	For additional information, see the <CITE>Apache Week</CITE> article on
	<A HREF="http://www.apacheweek.com/features/ssi" REL="Help"
	><CITE>Using Server Side Includes</CITE></A>.
	</P>
	<HR>
	</LI>

	<LI><A NAME="ssi-part-ii">
	<STRONG>Why don't my parsed files get cached?</STRONG>
	</A>
	<P>
	Since the server is performing run-time processing of your SSI
	directives, which may change the content shipped to the client, it
	can't know at the time it starts parsing what the final size of the
	result will be, or whether the parsed result will always be the same.
	This means that it can't generate <SAMP>Content-Length</SAMP> or
	<SAMP>Last-Modified</SAMP> headers. Caches commonly work by comparing
	the <SAMP>Last-Modified</SAMP> of what's in the cache with that being
	delivered by the server. Since the server isn't sending that header
	for a parsed document, whatever's doing the caching can't tell whether
	the document has changed or not - and so fetches it again to be on the
	safe side.
	</P>
	<P>
	You can work around this in some cases by causing an
	<SAMP>Expires</SAMP> header to be generated. (See the
	<A HREF="../mod/mod_expires.html" REL="Help"><SAMP>mod_expires</SAMP></A>
	documentation for more details.) Another possibility is to use the
	<A HREF="../mod/mod_include.html#xbithack" REL="Help"
	><SAMP>XBitHack Full</SAMP></A>
	mechanism, which tells Apache to send (under certain circumstances
	detailed in the XBitHack directive description) a
	<SAMP>Last-Modified</SAMP> header based upon the last modification
	time of the file being parsed. Note that this may actually be lying
	to the client if the parsed file doesn't change but the SSI-inserted
	content does; if the included content changes often, this can result
	in stale copies being cached.
	</P>
	<HR>
	</LI>

	<LI><A NAME="ssi-part-iii">
	<STRONG>How can I have my script output parsed?</STRONG>
	</A>
	<P>
	So you want to include SSI directives in the output from your CGI
	script, but can't figure out how to do it?
	The short answer is "you can't." This is potentially
	a security liability and, more importantly, it can not be cleanly
	implemented under the current server API. The best workaround
	is for your script itself to do what the SSIs would be doing.
	After all, it's generating the rest of the content.
	</P>
	<P>
	This is a feature The Apache Group hopes to add in the next major
	release after 1.3.
	</P>
	<HR>
	</LI>

	<LI><A NAME="ssi-part-iv">
	<STRONG>SSIs don't work for VirtualHosts and/or
	user home directories.</STRONG>
	</A>
	<P>
	This is almost always due to having some setting in your config file that
	sets "Options Includes" or some other setting for your DocumentRoot
	but not for other directories. If you set it inside a Directory
	section, then that setting will only apply to that directory.
	</P>
	<HR>
	</LI>

	<LI><A NAME="errordocssi">
	<STRONG>How can I use <CODE>ErrorDocument</CODE>
	and SSI to simplify customized error messages?</STRONG>
	</A>
	<P>
	Have a look at <A HREF="custom_errordocs.html">this document</A>.
	It shows in example form how you can a combination of XSSI and
	negotiation to tailor a set of <CODE>ErrorDocument</CODE>s to your
	personal taste, and returning different internationalized error
	responses based on the client's native language.
	</P>
	<HR>
	</LI>

	<LI><A NAME="remote-user-var">
	<STRONG>Why is the environment variable
	<SAMP>REMOTE_USER</SAMP> not set?</STRONG>
	</A>
	<P>
	This variable is set and thus available in SSI or CGI scripts <STRONG>if and
	only if</STRONG> the requested document was protected by access
	authentication. For an explanation on how to implement these restrictions,
	see
	<A HREF="http://www.apacheweek.com/"><CITE>Apache Week</CITE></A>'s
	articles on
	<A HREF="http://www.apacheweek.com/features/userauth"
	><CITE>Using User Authentication</CITE></A>
	or
	<A HREF="http://www.apacheweek.com/features/dbmauth"
	><CITE>DBM User Authentication</CITE></A>.
	</P>
	<P>
	Hint: When using a CGI script to receive the data of a HTML <SAMP>FORM</SAMP>
	notice that protecting the document containing the <SAMP>FORM</SAMP> is not
	sufficient to provide <SAMP>REMOTE_USER</SAMP> to the CGI script. You have
	to protect the CGI script, too. Or alternatively only the CGI script (then
	authentication happens only after filling out the form).
	</P>
	<HR>
	</LI>

	</OL>
	<!--#endif -->
	<!--#if expr="$STANDALONE" -->
	<!-- Don't forget to add HR tags at the end of each list item.. -->

	<!--#include virtual="footer.html" -->
	</BODY>
	</HTML>
	<!--#endif -->