1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
|
<!--#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 XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta name="generator" content="HTML Tidy, see www.w3.org" />
<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.11 $ ($Date: 2002/06/07 01:48:13 $)</p>
<p>The latest version of this FAQ is always available from the
main Apache web site, at <<a
href="http://httpd.apache.org/docs/misc/FAQ.html"
rel="Help"><samp>http://httpd.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>
<li><a href="#user-cgi">How do I allow each of my user
directories to have a cgi-bin directory?</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 id="CGIoutsideScriptAlias"
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>
<ol>
<li>
In an appropriate section of your server configuration
files, add a line such as
<dl>
<dd><code>AddHandler cgi-script .cgi</code></dd>
</dl>
<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>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>
<ol>
<li>
Locally add to the corresponding <samp>.htaccess</samp>
file a ruleset similar to this one:
<dl>
<dd><code>RewriteEngine on<br />
RewriteBase /~foo/bar/<br />
RewriteRule ^quux\.cgi$ -
[T=application/x-httpd-cgi]</code></dd>
</dl>
</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>
<hr />
</li>
<li>
<a id="premature-script-headers"
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>
<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>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 id="POSTnotallowed" 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 id="nph-scripts" 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 id="cgi-spec" 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 id="fastcgi" 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 id="ssi-part-i" 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 resource-consumptive compared to serving static
files, 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:
<dl>
<dd><code>AddHandler server-parsed .shtml</code></dd>
</dl>
<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 id="ssi-part-ii" 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 id="ssi-part-iii" 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 id="ssi-part-iv" 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 id="errordocssi" 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 id="remote-user-var" 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>
<li>
<a id="user-cgi" name="user-cgi"><strong>How do I allow
each of my user directories to have a cgi-bin
directory?</strong></a>
<p>Remember that CGI execution does not need to be
restricted only to cgi-bin directories. You can <a
href="#CGIoutsideScriptAlias">allow CGI script execution in
arbitrary parts of your filesystem</a>.</p>
<p>There are many ways to give each user directory a
cgi-bin directory such that anything requested as
<samp>http://example.com/~user/cgi-bin/program</samp> will
be executed as a CGI script. Two alternatives are:</p>
<ol>
<li>
Place the cgi-bin directory next to the public_html
directory:
<dl>
<dd><code>ScriptAliasMatch ^/~([^/]*)/cgi-bin/(.*)
/home/$1/cgi-bin/$2</code></dd>
</dl>
</li>
<li>
Place the cgi-bin directory underneath the public_html
directory:
<dl>
<dd><code><Directory
/home/*/public_html/cgi-bin><br />
Options ExecCGI<br />
SetHandler cgi-script<br />
</Directory></code></dd>
</dl>
</li>
</ol>
<p>If you are using suexec, the first technique will not work
because CGI scripts must be stored under the <code>public_html</code>
directory.</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" -->
<!--#endif -->
</body>
</html>
|
