From 49d6e906c9190543962e44ac43dd8129afd2c9cc Mon Sep 17 00:00:00 2001
From: "William A. Rowe Jr" <wrowe@apache.org>
Date: Mon, 14 Oct 2002 18:25:07 +0000
Subject: [PATCH]   Document EnableSendfile.  I'm presuming that
 directives.html* and   quick_reference.html* are now autogenerated.  Could
 someone run the   xml builder and commit the compiled results?

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@97208 13f79535-47bb-0310-9956-ffa450edef68
---
 docs/manual/misc/perf-tuning.xml | 33 ++++++++++++++++++
 docs/manual/mod/core.xml         | 59 ++++++++++++++++++++++++++++++++
 2 files changed, 92 insertions(+)

diff --git a/docs/manual/misc/perf-tuning.xml b/docs/manual/misc/perf-tuning.xml
index ddb3420d21..9c2c372e35 100644
--- a/docs/manual/misc/perf-tuning.xml
+++ b/docs/manual/misc/perf-tuning.xml
@@ -94,6 +94,7 @@
         <directive module="mod_dir">DirectoryIndex</directive>
         <directive module="core">HostnameLookups</directive>
         <directive module="core">EnableMMAP</directive>
+        <directive module="core">EnableSendfile</directive>
         <directive module="core">KeepAliveTimeout</directive>
         <directive module="prefork">MaxSpareServers</directive>
         <directive module="prefork">MinSpareServers</directive>
@@ -285,6 +286,38 @@ DirectoryIndex index.cgi index.pl index.shtml index.html
 
     </section>
 
+    <section>
+
+      <title>Sendfile</title>
+
+      <p>In situations where Apache 2.0 can ignore the contents of the file
+      to be delivered -- for example, when serving static file content -- 
+      it normally uses the kernel sendfile support the file if the OS 
+      supports the <code>sendfile(2)</code> operation.</p>
+
+      <p>On most platforms, using sendfile improves performance by eliminating
+      separate read and send mechanics.  However, there are cases where using
+      sendfile can harm the stability of the httpd:</p>
+
+      <ul>
+        <li>
+          <p>Some platforms may have broken sendfile support that the build
+          system did not detect, especially if the binaries were built on
+          another box and moved to such a machine with broken sendfile support.</p>
+        </li>
+        <li>
+          <p>With an NFS-mounted files, the kernel may be unable 
+          to reliably serve the network file through it's own cache.</p>
+        </li>
+      </ul>
+
+      <p>For installations where either of these factors applies, you
+      should use <code>EnableSendfile off</code> to disable sendfile
+      delivery of file contents. (Note: This directive can be overridden 
+      on a per-directory basis.)</p>
+
+    </section>
+
     <section>
 
       <title>Process Creation</title>
diff --git a/docs/manual/mod/core.xml b/docs/manual/mod/core.xml
index 11f214de10..c081ca4b78 100644
--- a/docs/manual/mod/core.xml
+++ b/docs/manual/mod/core.xml
@@ -642,6 +642,65 @@ Location</a></seealso>
     <example>
       EnableMMAP off
     </example>
+
+    <p>For NFS mounted files, this feature may be disabled explicitly for
+    the offending files by specifying:</p>
+
+    <example>
+      &lt;Directory "/path-to-nfs-files"&gt;
+            EnableMMAP off
+      &lt;/Directory&gt;
+    </example>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>EnableSendfile</name>
+<description>Use the kernel sendfile support to deliver files to the client</description>
+<syntax>EnableSendfile on|off</syntax>
+<default>EnableSendfile on</default>
+<contextlist><context>server config</context><context>virtual host</context>
+<context>directory</context><context>.htaccess</context>
+</contextlist>
+<override>FileInfo</override>
+
+<usage>
+    <p>This directive controls whether the httpd may use the sendfile
+    support from the kernel to transmit file contents to the client.
+    By default, when the handling of a request requires no access
+    to the data within a file -- for example, when delivering a
+    static file -- Apache uses sendfile to deliver the file contents
+    without ever reading the file if the OS supports it.</p>
+
+    <p>This sendfile mechanism avoids seperate read and send operations,
+    and buffer allocations.  But on some platforms or within some
+    filesystems, it is better to disable this feature to avoid 
+    operational problems:</p>
+
+    <ul>
+    <li>Some platforms may have broken sendfile support that the build
+    system did not detect, especially if the binaries were built on
+    another box and moved to such a machine with broken sendfile support.</li>
+    <li>With an NFS-mounted <directive module="core">DocumentRoot</directive>,
+    the kernel may be unable to serve the network file through 
+    it's own cache.</li>
+    </ul>
+
+    <p>For server configurations that are vulnerable to these problems,
+    you should disable memory-mapping of delivered files by specifying:</p>
+
+    <example>
+      EnableSendfile off
+    </example>
+
+    <p>For NFS mounted files, this feature may be disabled explicitly for
+    the offending files by specifying:</p>
+
+    <example>
+      &lt;Directory "/path-to-nfs-files"&gt;
+            EnableSendfile off
+      &lt;/Directory&gt;
+    </example>
 </usage>
 </directivesynopsis>
 
-- 
2.40.0