Commit f4bc0d95 authored by dgaudet's avatar dgaudet
Browse files

Merge in all of the docs from HEAD, I'll clean it up a bit later. 

Reviewed by:
Submitted by:
Obtained from:


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/APACHE_1_2_X@78392 13f79535-47bb-0310-9956-ffa450edef68
parent 40dd1a15

docs/manual/misc/FAQ.html

+181 −23
Original line number Diff line number Diff line
@@ -15,7 +15,7 @@ 
  <!--#include virtual="header.html" -->

  <H1 ALIGN="CENTER">Apache Server Frequently Asked Questions</H1>

  <P>

  $Revision: 1.63.2.2 $ ($Date: 1997/06/11 21:21:39 $)

  $Revision: 1.63.2.3 $ ($Date: 1997/06/27 03:02:04 $)

  </P>

  <P>

  The latest version of this FAQ is always available from the main
@@ -131,6 +131,8 @@ 
   <LI><A HREF="#fdlim">Why can't I run more than &lt;<EM>n</EM>&gt;

    virtual hosts?</A>

   </LI>

   <LI><A HREF="#freebsd-setsize">Can I increase FD_SETSIZE on FreeBSD?</A>

   </LI>

   <LI><A HREF="#limitGET">Why do I keep getting &quot;access denied&quot; for

    form POST requests?</A>

   </LI>
@@ -205,6 +207,15 @@ 
   </LI>

   <LI><A HREF="#no-info-directives">Why doesn't mod_info list any

    directives?</A>

   <LI><A HREF="#linux-shmget">When I run it under Linux I get "shmget:

    function not found", what should I do?</A>

   </LI>

   <LI><A HREF="#authauthoritative">Why does my authentification give

    me a server error?</A>

   <LI><A HREF="#auth-on-same-machine">Do I have to keep the (mSQL)

      authentification information on the same machine?</A>

   </LI>

   <LI><A HREF="#msql-slow">Why is my mSQL authentification terribly slow?</A>

   </LI>

  </OL>

 </LI>
@@ -569,17 +580,36 @@ 
  <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.  The most common cause of this (aside from people not

  outputting the required headers at all) a result of an interaction

  with perl's output buffering.  To make perl flush its buffers 

  after each output statement, insert the following statements before your

  first <CODE>print</CODE> or <CODE>write</CODE> statement:

  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.

  </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>$cfh = select (STDOUT);<BR>

    $| = 1;<BR>

    select ($cfh);</CODE>

   <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>
@@ -588,8 +618,10 @@ 
  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 maximise performance, you should

  turn buffering back <EM>on</EM> (with <CODE>$| = 0</CODE> or the

  equivalent) after the statements that send the headers.

  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
@@ -796,8 +828,9 @@ 
        HREF="../mod/core.html#listen"

       ><SAMP>Listen</SAMP></A>

       directives.  If there are no other servers running on the machine 

       and all of them are running on the same port, you normally don't 

       need any Listen directives at all.

       on the same port then you normally don't

       need any Listen directives at all.  By default Apache listens to

       all addresses on port 80.

   </LI>

   <LI>Reduce the number of log files.  You can use 

       <A
@@ -815,7 +848,8 @@ 
       <A

        HREF="perf.html"

       >performance hints</A>

       page.

       page.  There is a specific note for

       <a href="#freebsd-setsize">FreeBSD</a> below.

   </LI>

   <LI>&quot;Don't do that&quot; - try to run with fewer virtual hosts

   </LI>
@@ -831,6 +865,24 @@ 
  available in the way of solutions.

  </P>

  <HR>



 <LI><A NAME="freebsd-setsize">

      <STRONG>Can I increase FD_SETSIZE on FreeBSD?</STRONG>

     </A>

  <P>

    On FreeBSD 2.2 and older FD_SETSIZE, which limits the number of open

    files on the system, is limted to 256. This can limit the number of

    virtual hosts you are using; especially if they all use different log

    files. Increasing this limit (and recompiling apache) is not enough

    (As it is on some platforms, such as Solaris), as you also will have

    to recompile libc with the changed setting.

  </P>

  <p>

    On FreeBSD 3.0 the default is 1024, so the problem is lessened.

  </p>

  <HR>

 </LI>



 <LI><A NAME="limitGET">

      <STRONG>Why do I keep getting &quot;access denied&quot; for form POST

      requests?</STRONG>
@@ -1113,7 +1165,7 @@ 
  </P>

  <P>

  <DL>

   <DD><CODE>if ($0 =~ m:/*nph-:) {

   <DD><CODE>if ($0 =~ m:^(.*/)*nph-[^/]*$:) {

    <BR>

    &nbsp;&nbsp;&nbsp;&nbsp;

    $HTTP_headers&nbsp;=&nbsp;
@@ -1124,9 +1176,9 @@ 
    &quot;Connection:&nbsp;close\015\012&quot;;

    <BR>

    &nbsp;&nbsp;&nbsp;&nbsp;

    printf&nbsp;($HTTP_headers);

    print&nbsp;$HTTP_headers;

    <BR>

    };</CODE>

    }</CODE>

   </DD>

  </DL>

  </P>
@@ -1137,7 +1189,8 @@ 
 </LI>

 <LI><A NAME="linuxiovec">

      <STRONG>Why do I get complaints about redefinition

      of &quot;<CODE>struct iovec</CODE>&quot; when compiling under Linux?</STRONG>

      of &quot;<CODE>struct iovec</CODE>&quot; when

      compiling under Linux?</STRONG>

     </A>

  <P>

  This is a conflict between your C library includes and your kernel
@@ -1540,6 +1593,111 @@ 
  <HR>

 </LI>



 <LI><A NAME="linux-shmget">

      <STRONG>When I run it under Linux I get "shmget:

      function not found", what should I do?</STRONG>

     </A>

  <P>

    Your kernel has been built without SysV IPC support.  You will have to

    rebuild the kernel with that support enabled (it's under the

    "General Setup" submenu).  Documention for

    kernel building is beyond the scope of this FAQ, you should consult

    the <A HREF="http://www.linuxhq.com/HOWTO/Kernel-HOWTO.html">Kernel

    HOWTO</A>, or the documentation provided with your distribution,

    or a <A HREF="http://www.linuxhq.com/HOWTO/META-FAQ.html">Linux

    newsgroup/mailing list</A>.  As a last resort workaround, you can

    comment out the <CODE>#define HAVE_SHMGET</CODE> definition in the

    <CODE>LINUX</CODE> section of

    <CODE>src/conf.h</CODE> and rebuild the server.  This will produce

    a server which is slower and less reliable.

  </P>

  <HR>

 </LI>



 <LI><A NAME="authauthoritative">

      <STRONG>Why does my authentification give me a server error?</STRONG>

     </A>

  <P>

    Under normal circumstances, the apache access control modules will

    pass unrecognized userids on to the next access control module in

    line.  Only if the userid is recognized, the password is validated

    (or not) will it give the usual success or authentification failed

    messages.

  </p>

  <p>

    However if the last access module in line 'declines' the validation

    request (because it has never heard of the userid or because it is not

    configured) the http_request handler will give one of the following,

    confusing, errors:

  <UL>

    <li> <code>check access</code>

    <li> <code>check user.  No user file? </code>

    <li> <code>check access.  No groups file? </code>

  </ul> 

    This does not mean that you have to add a 'AuthUserFile /dev/null'

    line as some magazines suggest !

  </p>

  <p>

    The solution is to ensure that at least the last module is authoritative

    and <b>CONFIGURED</b>. By default <code>mod_auth</code> is authoritative

    and will give an OK/Denied, but only if it is configured with the

    proper AuthUserFile. Likewise if a valid group is required.  (Remember

    that the modules are processed in the reverse order they appear in

    your compile-time Configuration file.)

  </P>

  <p>

    A typical situation for this error is when you are using the

    mod_auth_dbm, mod_auth_msql, mod_auth_mysql, mod_auth_anon or

    mod_auth_cookie on their own.  These are by default <b>not</b>

    authoritative, and this will pass the buck on to the (non-existent) next

    authentification module when the user ID is not in their respective

    database.  Just add the appropriate 'XXXAuthoritative yes' line to

    the configuration.

  </p>

  <p>

    In general it is a good idea (though not terribly efficient) to have the

    file based mod_auth a module of last resort. This allows you to access

    the web server with a few special passwords even if the databases are

    down or corrupted.  This does cost a file-open/seek/close for each

    request in a protected area.

  </p>

  <HR>

 </LI>



 <LI><A NAME="auth-on-same-machine">

      <STRONG>Do I have to keep the (mSQL) authentification information

      on the same machine?</STRONG>

     </A>

  <p>

    Some organizations feel very strongly about keeping the authentification

    information on a different machine than the webserver. With the

    mod_auth_msql, mod_auth_mysql and other SQL modules connecting to

    (R)DBMses this is quite well possible. Just configure an explicit host

    to contact.

  </p>

  <p>

    Be aware that with mSQL and Oracle, opening and closing these database

    connections is very expensive and time consuming. You might want to

    look at the code in the auth_modules and play with the compile time

    flags to alleviate this somewhat; if your RDBMS licences alows for it.

  </p>

  <HR>

 </LI>



 <LI><A NAME="msql-slow">

      <STRONG>Why is my mSQL authentification terribly slow?</STRONG>

     </A>

  <p>

    You have probably configured the Host by specificing a FQHN,

    and thus the libmsql will use a full blown tcp/ip socket to talk to

    the database, rather than a fast internal device. Both the libmsql,

    the mSQL faq and the mod_auth_msql documentation warn you about this. If

    you have to use different hosts, check out the mod_auth_msql code for

    some compile time flags which might, or might not suit you.

  </p>

 <HR>

 </LI>



  <!-- Don't forget to add HR tags at the end of each list item.. -->



</OL>

docs/manual/misc/compat_notes.html

+4 −0
Original line number Diff line number Diff line
@@ -33,6 +33,7 @@ href="http://www.apache.org/bugdb.cgi">let us know.</a> 
<LI>The basic mod_auth <CODE>AuthGroupFile</CODE>-specified group file 

    format allows commas between user names - Apache does not.<BR>

    <I>- added 12/1/96</I>

  <p>



  <LI><P>If you follow the NCSA guidelines for setting up access restrictions

  based on client domain, you may well have added entries for,
@@ -99,6 +100,9 @@ it added one automatically if the .asis file contained a Location header. 
  files if the last line does not have a trailing newline. This affects

  configuration files (httpd.conf, access.conf and srm.conf), and

  htpasswd and htgroup files.

  </LI>



  <LI>Apache does not permit commas delimiting the methods in &lt;Limit&gt;.

 

</OL>

docs/manual/mod/core.html

+4 −1
Original line number Diff line number Diff line
@@ -836,6 +836,9 @@ Execution of CGI scripts is permitted. 
<dd>

<!--%plaintext &lt;?INDEX {\tt FollowSymLinks} option&gt; -->

The server will follow symbolic links in this directory.

<b>Note</b>: even though the server follows the symlink it does <i>not</i>

change the pathname used to match against <code>&lt;Directory&gt;</code>

sections.

<dt>Includes

<dd>

<!--%plaintext &lt;?INDEX {\tt Includes} option&gt; -->
@@ -1158,7 +1161,7 @@ release.<p> 
<A name="sendbuffersize"><h2>SendBufferSize directive</h2></A>

<!--%plaintext &lt;?INDEX {\tt SendBufferSize} directive&gt; -->

<strong>Syntax:</strong> SendBufferSize <em>bytes</em><br>

<strong>Context:</strong> server config, virtual host<br>

<strong>Context:</strong> server config<br>

<strong>Status:</strong> core<p>



The server will set the TCP buffer size to the number of bytes

docs/manual/mod/mod_dir.html

+20 −0
Original line number Diff line number Diff line
@@ -324,6 +324,26 @@ This will suppress the file size in fancy indexing listings. 
<dd>

<!--%plaintext &lt;?INDEX {\tt SuppressDescription} index option&gt; -->

This will suppress the file description in fancy indexing listings.

<dt>IconHeight[=pixels] (<EM>Apache 1.3 and later</EM>)

<dd>

<!--%plaintext &lt;?INDEX {\tt IconHeight} index option&gt; -->

Presence of this option, when used with IconWidth, will cause the server

to include <SAMP>HEIGHT</SAMP> and <SAMP>WIDTH</SAMP> attributes in the

<SAMP>IMG</SAMP> tag for the file icon.  This allows browser to

precalculate the page layout without having to wait until all the

images have been loaded.  If no value is given for the option, it

defaults to the standard height of the icons supplied with the Apache

software.

<dt>IconWidth[=pixels] (<EM>Apache 1.3 and later</EM>)

<dd>

<!--%plaintext &lt;?INDEX {\tt IconWidth} index option&gt; -->

Presence of this option, when used with IconHeight, will cause the server

to include <SAMP>HEIGHT</SAMP> and <SAMP>WIDTH</SAMP> attributes in the

<SAMP>IMG</SAMP> tag for the file icon.  This allows browser to

precalculate the page layout without having to wait until all the

images have been loaded.  If no value is given for the option, it

defaults to the standard width of the icons supplied with the Apache

software.

</dl>

This default is that no options are enabled. If multiple IndexOptions

could apply to a directory, then the most specific one is taken complete;

docs/manual/suexec.html

+157 −156
Original line number Diff line number Diff line
@@ -21,10 +21,11 @@ 
        <LI><A HREF="#what">What is suEXEC?</A></LI>

        <LI><A HREF="#before">Before we begin.</A></LI>

        <LI><A HREF="#model">suEXEC Security Model.</A></LI>

	<LI><A HREF="#install">Configuring & Installing suEXEC</A></LI>

	<LI><A HREF="#enable">Enabling & Disabling suEXEC</A></LI>

        <LI><A HREF="#install">Configuring &amp; Installing suEXEC</A></LI>

        <LI><A HREF="#enable">Enabling &amp; Disabling suEXEC</A></LI>

        <LI><A HREF="#debug">Debugging suEXEC</A></LI>

	<LI><A HREF="#jabberwock">Beware the Jabberwock: Warnings & Examples</A></LI>

        <LI><A HREF="#jabberwock">Beware the Jabberwock: Warnings &amp;

         Examples</A></LI> 

</OL>

</P>
@@ -257,7 +258,7 @@ section of this document. 
<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG>

</P>



<H3><A NAME="install">Configuring & Installing suEXEC</A></H3>

<H3><A NAME="install">Configuring &amp; Installing suEXEC</A></H3>

<P ALIGN="LEFT">

Here's where we begin the fun.  The configuration and installation of suEXEC is

a four step process: edit the suEXEC header file, compile suEXEC, place the
@@ -396,7 +397,7 @@ user shell, do so now and execute the following commands. 
<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG>

</P>



<H3><A NAME="enable">Enabling & Disabling suEXEC</A></H3>

<H3><A NAME="enable">Enabling &amp; Disabling suEXEC</A></H3>

<P ALIGN="LEFT">

After properly installing the <STRONG>suexec</STRONG> wrapper

executable, you must kill and restart the Apache server.  A simple
@@ -454,7 +455,7 @@ and the error_log for the server to see where you may have gone astray. 
<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG>

</P>



<H3><A NAME="jabberwock">Beware the Jabberwock: Warnings & Examples</A></H3>

<H3><A NAME="jabberwock">Beware the Jabberwock: Warnings &amp; Examples</A></H3>

<P ALIGN="LEFT">

<STRONG>NOTE!</STRONG>  This section may not be complete.  For the latest

revision of this section of the documentation, see the Apache Group's

docs/manual/process-model.html

+3 −3

File changed.

Contains only whitespace changes.

docs/manual/misc/fin_wait_2.html

+57 −57

File changed.

Contains only whitespace changes.

docs/manual/misc/index.html

+14 −14

File changed.

Contains only whitespace changes.

docs/manual/mod/mod_auth_anon.html

+40 −40

File changed.

Contains only whitespace changes.

docs/manual/custom-error.html

+2 −2

File changed.

Contains only whitespace changes.

docs/manual/mod/mod_include.html

+6 −6

File changed.

Contains only whitespace changes.

docs/manual/mod/mod_proxy.html

+2 −2

File changed.

Contains only whitespace changes.

docs/manual/mod/mod_rewrite.html

+4 −4

File changed.

Contains only whitespace changes.

docs/manual/mod/mod_status.html

+1 −1

File changed.

Contains only whitespace changes.