From: Eric Covener <covener@apache.org>
Date: Tue, 3 Jan 2012 20:37:22 +0000 (+0000)
Subject: Merge r1226603, r1226775 from trunk:
X-Git-Tag: 2.4.0~25
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=9d61a32935babab73a39723623def6052922b73e;p=apache

Merge r1226603, r1226775 from trunk:

fill in the heartbeat modules' documentation.


add heartbeat to list of lb methods living in other modules.



git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x@1226940 13f79535-47bb-0310-9956-ffa450edef68
---

diff --git a/docs/manual/mod/mod_heartbeat.xml b/docs/manual/mod/mod_heartbeat.xml
index d1485fc90b..ca824e647d 100644
--- a/docs/manual/mod/mod_heartbeat.xml
+++ b/docs/manual/mod/mod_heartbeat.xml
@@ -23,24 +23,33 @@
 <modulesynopsis metafile="mod_heartbeat.xml.meta">
 
 <name>mod_heartbeat</name>
-<description></description>
-<status>Extension</status>
-<sourcefile>mod_heartbeat.c</sourcefile>
+<description>sends messages with server status to frontend proxy</description>
+<status>Experimental</status>
+<sourcefile>mod_heartbeat</sourcefile>
 <identifier>heartbeat_module</identifier>
-<compatibility>Available in 2.3 and later</compatibility>
+<compatibility>Available in Apache 2.3 and later</compatibility>
 
 <summary>
-    <note><!-- FIXME: -->This document is still under development.</note>
+<p> <module>mod_heartbeat</module> sends multicast messages to a <module>mod_heartmonitor</module> listener 
+that advertises the servers current connection count.  Usually, <module>mod_heartmonitor</module>
+will be running on a proxy server with <module>mod_lbmethod_heartbeat</module> loaded, which allows
+<directive module="mod_proxy">ProxyPass</directive> to use the "heartbeat" <em>lbmethod</em> inside
+of <directive module="mod_proxy">ProxyPass</directive>.</p>
 </summary>
 
 <directivesynopsis>
 <name>HeartbeatAddress</name>
 <description>Address to send heartbeat requests</description>
-<syntax></syntax>
+<syntax>HeartbeatAddress <var>addr:port</var></syntax>
+<default>disabled</default>
 <contextlist><context>server config</context></contextlist>
 
 <usage>
-    <note><!-- FIXME: -->This document is still under development.</note>
+    <p>The <directive>HeartbeatAddress</directive> directive specifies the 
+    address <module>mod_heartbeat</module> will send status information to. This
+    address will usually corrspond to a configured  <directive
+    module="mod_heartmonitor">HeartbeatListen</directive> on a frontend
+    proxy system.  </p>
 </usage>
 </directivesynopsis>
 
diff --git a/docs/manual/mod/mod_heartmonitor.xml b/docs/manual/mod/mod_heartmonitor.xml
index 6ba3380a64..9028040f56 100644
--- a/docs/manual/mod/mod_heartmonitor.xml
+++ b/docs/manual/mod/mod_heartmonitor.xml
@@ -20,27 +20,45 @@
  limitations under the License.
 -->
 
-<modulesynopsis metafile="mod_heartmonitor.xml.meta">
+<modulesynopsis metafile="mod_heartbeat.xml.meta">
 
 <name>mod_heartmonitor</name>
-<description></description>
-<status>Extension</status>
-<sourcefile>mod_heartmonitor.c</sourcefile>
+<description>centralized monitor for mod_heartbeat origin servers</description>
+<status>Experimental</status>
+<sourcefile>mod_heartmonitor</sourcefile>
 <identifier>heartmonitor_module</identifier>
-<compatibility>Available in 2.3 and later</compatibility>
+<compatibility>Available in Apache 2.3 and later</compatibility>
 
 <summary>
-    <note><!-- FIXME: -->This document is still under development.</note>
+<p>
+<module>mod_heartmonitor</module> listens for server status messages generated 
+by <module>mod_heartbeat</module> enabled servers and makes their status 
+available to <module>mod_lbmethod_heartbeat</module>. This allows 
+<directive module="mod_proxy">ProxyPass</directive> to use the "heartbeat" 
+<em>lbmethod</em> inside of <directive module="mod_proxy">ProxyPass</directive>.
+</p>
+
+<p>This module uses the services of <module>mod_slotmem_shm</module> when
+available instead of flat-file storage.  No configuration is required to
+use <module>mod_slotmem_shm</module>.</p>
 </summary>
 
 <directivesynopsis>
 <name>HeartbeatListen</name>
-<description>Address to listen for heartbeat requests</description>
-<syntax></syntax>
+<description>address to listen for incoming heartbeat requests </description>
+<syntax>HeartbeatListen<var>addr:port</var></syntax>
+<default>disabled</default>
 <contextlist><context>server config</context></contextlist>
 
 <usage>
-    <note><!-- FIXME: -->This document is still under development.</note>
+    <p>The <directive>HeartbeatListen</directive> directive specifies the
+    address the server will listen on for status information from 
+    <module>mod_heartbeat</module>-enabled servers.  This
+    address will usually corrspond to a configured  <directive
+    module="mod_heartbeat">HeartbeatAddress</directive> on an origin server.
+    </p>
+
+    <p> This module is inactive until this directive is used.</p>
 </usage>
 </directivesynopsis>
 
@@ -52,8 +70,25 @@
 <contextlist><context>server config</context></contextlist>
 
 <usage>
-    <note><!-- FIXME: -->This document is still under development.</note>
+    <p>The <directive>HeartbeatStorage</directive> directive specifies the
+    path to store heartbeat data.  This flat-file is used only when
+    <module>mod_slotmem_shm</module> is not loaded.</p>
 </usage>
 </directivesynopsis>
 
+<directivesynopsis>
+<name>HeartbeatMaxServers</name>
+<description>Specifies the maximum number of servers that will be sending 
+heartbeat requests to this server</description>
+<syntax>HeartbeatMaxServers <var>number-of-servers</var></syntax>
+<default>HeartbeatMaxServers 10</default>
+<contextlist><context>server config</context></contextlist>
+
+<usage>
+    <p>The <directive>HeartbeatMaxServers</directive> directive specifies the
+    maximum number of servers that will be sending requests to this monitor
+    server.  It is used to control the size of the shared memory allocated
+    to store the heartbeat info.</p>
+</usage>
+</directivesynopsis>
 </modulesynopsis>
diff --git a/docs/manual/mod/mod_lbmethod_heartbeat.xml b/docs/manual/mod/mod_lbmethod_heartbeat.xml
index 7e831c55e5..26dfa88433 100644
--- a/docs/manual/mod/mod_lbmethod_heartbeat.xml
+++ b/docs/manual/mod/mod_lbmethod_heartbeat.xml
@@ -23,15 +23,24 @@
 <modulesynopsis metafile="mod_lbmethod_heartbeat.xml.meta">
 
 <name>mod_lbmethod_heartbeat</name>
-<description><!-- FIXME: --> This document is still under development.</description>
-<status>Extension</status>
+<description>Heartbeat Traffic Counting load balancer scheduler algorithm for <module
+>mod_proxy_balancer</module></description>
+<status>Experimental</status>
 <sourcefile>mod_lbmethod_heartbeat.c</sourcefile>
 <identifier>lbmethod_heartbeat_module</identifier>
 <compatibility>Available in version 2.3 and later</compatibility>
 
 <summary>
-    <note><!-- FIXME: --> This document is still under development.</note>
+<p>lbmethod=heartbeat uses the services of <module
+>mod_heartmonitor</module> to balance between origin servers that are providing
+heartbeat info via the <module>mod_heartbeat module</module>.</p>
+
+<p> This modules load balancing algorithm favors servers with more ready (idle)
+capacity over time, but does not select the server with the most ready capacity 
+every time.  Servers that have 0 active clients are penalized, with the 
+assumption that they are not fully initialized.</p>
 </summary>
+
 <seealso><module>mod_proxy</module></seealso>
 <seealso><module>mod_proxy_balancer</module></seealso>
 <seealso><module>mod_heartbeat</module></seealso>
@@ -45,8 +54,9 @@
 <contextlist><context>server config</context></contextlist>
 
 <usage>
-    <note><!-- FIXME: -->This document is still under development.</note>
+    <p>The <directive>HeartbeatStorage</directive> directive specifies the
+    path to read heartbeat data.  This flat-file is used only when
+    <module>mod_slotmem_shm</module> is not loaded.</p>
 </usage>
 </directivesynopsis>
-
 </modulesynopsis>
diff --git a/docs/manual/mod/mod_proxy_balancer.xml b/docs/manual/mod/mod_proxy_balancer.xml
index 97fed36667..bc6160c7d4 100644
--- a/docs/manual/mod/mod_proxy_balancer.xml
+++ b/docs/manual/mod/mod_proxy_balancer.xml
@@ -38,8 +38,9 @@
     <p>Load balancing scheduler algorithm is provided by not this
     module but other modules such as:
     <module>mod_lbmethod_byrequests</module>,
-    <module>mod_lbmethod_bytraffic</module> and
-    <module>mod_lbmethod_bybusyness</module>.
+    <module>mod_lbmethod_bytraffic</module>,
+    <module>mod_lbmethod_bybusyness</module> and
+    <module>mod_lbmethod_heartbeat</module>.
     </p>
 
     <p>Thus, in order to get the ability of load balancing,