mirror of
https://github.com/apache/httpd.git
synced 2025-10-31 19:10:37 +03:00
a8857a3d7a
browsing with SSIs but more easily posted on USENET. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@83378 13f79535-47bb-0310-9956-ffa450edef68
510 lines
18 KiB
HTML
510 lines
18 KiB
HTML
<!--#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.1 $ ($Date: 1999/06/24 15:02:52 $)
|
|
</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.
|
|
</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>
|
|
<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 -->
|