| <!--#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 --> |