Update docs for proxy:

  1. Put params in abc order
  2. Add hot-standby example
  3. Add in new features that hadn't been documented yet (lbset, ...)


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@432352 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 88 insertions, 64 deletions

diff --git a/docs/manual/mod/mod_proxy.xml b/docs/manual/mod/mod_proxy.xml
index cc7eca1a5e..387162c756 100644
--- a/docs/manual/mod/mod_proxy.xml
+++ b/docs/manual/mod/mod_proxy.xml
@@ -556,20 +556,6 @@ expressions</description>
     number of connections will be created on demand. Any connections above 
     <code>smax</code> are subject to a time to live or <code>ttl</code>.
     </td></tr>
-    <tr><td>ttl</td>
-        <td>-</td>
-        <td>Time To Live for the inactive connections above the
-        <code>smax</code> connections in seconds. Apache will close all
-        connections that has not been used inside that time period.
-    </td></tr>
-    <tr><td>timeout</td>
-        <td><directive>Timeout</directive></td>
-        <td>Connection timeout in seconds.
-        If not set the Apache will wait until the free connection
-        is available. This directive is used for limiting the number
-        of connections to the backend server together with <code>max</code>
-        parameter.
-    </td></tr>
     <tr><td>acquire</td>
         <td>-</td>
         <td>If set this will be the maximum time to wait for a free
@@ -577,6 +563,20 @@ expressions</description>
     in the pool the Apache will return <code>SERVER_BUSY</code> status to
     the client.
     </td></tr>
+    <tr><td>flushpackets</td>
+        <td>off</td>
+        <td>Determines whether the proxy module will auto-flush the output
+        brigade after each "chunk" of data. 'off' means that it will flush
+        only when needed, 'on' means after each chunk is sent and
+        'auto' means poll/wait for a period of time and flush if
+        no input has been received for 'flushwait' milliseconds.
+        Currently this is in effect only for AJP.
+    </td></tr>
+    <tr><td>flushwait</td>
+        <td>10</td>
+        <td>The time to wait for additional input, in milliseconds, before
+        flushing the output brigade if 'flushpackets' is 'auto'.
+    </td></tr>
     <tr><td>keepalive</td>
         <td>Off</td>
         <td>This parameter should be used when you have a firewall between your
@@ -586,13 +586,11 @@ expressions</description>
     generally 120ms), and thus prevent the firewall to drop the connection.
     To enable keepalive set this property value to <code>On</code>. 
     </td></tr>
-    <tr><td>retry</td>
-        <td>60</td>
-        <td>Connection pool worker retry timeout in seconds.
-    If the connection pool worker to the backend server is in the error state,
-    Apache will not forward any requests to that server until the timeout
-    expires. This enables to shut down the backend server for maintenance,
-    and bring it back online later.
+    <tr><td>lbset</td>
+        <td>0</td>
+        <td>Sets the load balancer cluster set that the worker is a member
+         of. The load balancer will try all members of a lower numbered
+         lbset before trying higher numbered ones.
     </td></tr>
     <tr><td>loadfactor</td>
         <td>1</td>
@@ -600,10 +598,19 @@ expressions</description>
          It is a number between 1 and 100 and defines the normalized weighted
          load applied to the worker.
     </td></tr>
-    <tr><td>route</td>
-        <td>-</td>
-        <td>Route of the worker when used inside load balancer.
-        The route is a value appended to seesion id.
+    <tr><td>ping</td>
+        <td>0</td>
+        <td>Ping property told webserver to send a <code>CPING</code>
+        request on ajp13 connection before forwarding to it a request.
+        The parameter is the delay in seconds to wait for the
+        <code>CPONG</code> reply.
+        This features has been added to avoid problem with hung and
+        busy Tomcat's and require ajp13 ping/pong support which has
+        been implemented on Tomcat 3.3.2+, 4.1.28+ and 5.0.13+.
+        It will inrease the network traffic during the normal operation
+        which could be an issue for you, but it will lower down the
+        traffic in case some of the cluster nodes are down or buys.
+        Currently this is in effect only for AJP.
     </td></tr>
     <tr><td>redirect</td>
         <td>-</td>
@@ -613,42 +620,41 @@ expressions</description>
         redirected to the BalancerMember that has route parametar
         equal as this value.
     </td></tr>
+    <tr><td>retry</td>
+        <td>60</td>
+        <td>Connection pool worker retry timeout in seconds.
+    If the connection pool worker to the backend server is in the error state,
+    Apache will not forward any requests to that server until the timeout
+    expires. This enables to shut down the backend server for maintenance,
+    and bring it back online later.
+    </td></tr>
+    <tr><td>route</td>
+        <td>-</td>
+        <td>Route of the worker when used inside load balancer.
+        The route is a value appended to seesion id.
+    </td></tr>
     <tr><td>status</td>
         <td>-</td>
         <td>Single letter value defining the initial status of
-        this worker: 'D' is disabled, 'S' is stopped and 'E' is
-        in an error state. Status can be set (which is the default)
+        this worker: 'D' is disabled, 'S' is stopped, 'H' is hot-standby
+        and 'E' is in an error state. Status can be set (which is the default)
         by prepending with '+' or cleared by prepending with '-'.
         Thus, a setting of 'S-E' sets this worker to Stopped and
         clears the in-error flag.
     </td></tr>
-    <tr><td>flushpackets</td>
-        <td>off</td>
-        <td>Determines whether the proxy module will auto-flush the output
-        brigade after each "chunk" of data. 'off' means that it will flush
-        only when needed, 'on' means after each chunk is sent and
-        'auto' means poll/wait for a period of time and flush if
-        no input has been received for 'flushwait' milliseconds.
-        Currently this is in effect only for AJP.
-    </td></tr>
-    <tr><td>flushwait</td>
-        <td>10</td>
-        <td>The time to wait for additional input, in milliseconds, before
-        flushing the output brigade if 'flushpackets' is 'auto'.
+    <tr><td>timeout</td>
+        <td><directive>Timeout</directive></td>
+        <td>Connection timeout in seconds.
+        If not set the Apache will wait until the free connection
+        is available. This directive is used for limiting the number
+        of connections to the backend server together with <code>max</code>
+        parameter.
     </td></tr>
-    <tr><td>ping</td>
-        <td>0</td>
-        <td>Ping property told webserver to send a <code>CPING</code>
-        request on ajp13 connection before forwarding to it a request.
-        The parameter is the delay in seconds to wait for the
-        <code>CPONG</code> reply.
-        This features has been added to avoid problem with hung and
-        busy Tomcat's and require ajp13 ping/pong support which has
-        been implemented on Tomcat 3.3.2+, 4.1.28+ and 5.0.13+.
-        It will inrease the network traffic during the normal operation
-        which could be an issue for you, but it will lower down the
-        traffic in case some of the cluster nodes are down or buys.
-        Currently this is in effect only for AJP.
+    <tr><td>ttl</td>
+        <td>-</td>
+        <td>Time To Live for the inactive connections above the
+        <code>smax</code> connections in seconds. Apache will close all
+        connections that has not been used inside that time period.
     </td></tr>
 
     </table>
@@ -657,24 +663,23 @@ expressions</description>
     <code>balancer://</code> then a virtual worker that does not really
     communicate with the backend server will be created. Instead it is responsible
     for the management of several "real" workers. In that case the special set of
-    parameters can be add to this virtual worker.
+    parameters can be add to this virtual worker. See <module>mod_proxy_balancer</module>
+    for more information about how the balancer works.
     </p>
     <table>
     <tr><th>Parameter</th>
         <th>Default</th>
         <th>Description</th></tr>
     <tr><td>lbmethod</td>
-        <td>-</td>
+        <td>byrequests</td>
         <td>Balancer load-balance method. Select the load-balancing scheduler
         method to use. Either <code>byrequests</code>, to perform weighted
         request counting or <code>bytraffic</code>, to perform weighted
         traffic byte count balancing. Default is <code>byrequests</code>.
     </td></tr>
-    <tr><td>stickysession</td>
-        <td>-</td>
-        <td>Balancer sticky session name. The value is usually set to something
-        like <code>JSESSIONID</code> or <code>PHPSESSIONID</code>,
-        and it depends on the backend application server that support sessions.
+    <tr><td>maxattempts</td>
+        <td>1</td>
+        <td>Maximum number of failover attempts before giving up. 
     </td></tr>
     <tr><td>nofailover</td>
         <td>Off</td>
@@ -682,17 +687,20 @@ expressions</description>
         error state or disabled. Set this value to On if backend servers do not
         support session replication.
     </td></tr>
+    <tr><td>stickysession</td>
+        <td>-</td>
+        <td>Balancer sticky session name. The value is usually set to something
+        like <code>JSESSIONID</code> or <code>PHPSESSIONID</code>,
+        and it depends on the backend application server that support sessions.
+    </td></tr>
     <tr><td>timeout</td>
         <td>0</td>
         <td>Balancer timeout in seconds. If set this will be the maximum time
         to wait for a free worker. Default is not to wait. 
     </td></tr>
-    <tr><td>maxattempts</td>
-        <td>1</td>
-        <td>Maximum number of failover attempts before giving up. 
-    </td></tr>
     
     </table>
+    <p>A sample balancer setup</p>
     <example>
       ProxyPass /special-area http://special.example.com/ smax=5 max=10<br />
       ProxyPass / balancer://mycluster/ stickysession=jsessionid nofailover=On<br />
@@ -705,6 +713,22 @@ expressions</description>
       </indent>
       &lt;/Proxy&gt;
     </example>
+
+    <p>Setting up a hot-standby, that will only be used if no other
+     members are available</p>
+    <example>
+      ProxyPass / balancer://hotcluster/ <br />
+      &lt;Proxy balancer://hotcluster&gt;<br />
+      <indent>
+        BalancerMember http://1.2.3.4:8009 loadfactor=1<br />
+        BalancerMember http://1.2.3.5:8009 loadfactor=2<br />
+        # The below is the hot standby<br />
+        BalancerMember http://1.2.3.6:8009 status=+H<br />
+        ProxySet lbmethod=bytraffic
+      </indent>
+      &lt;/Proxy&gt;
+    </example>
+
     
     <p>When used inside a <directive type="section" module="core"
     >Location</directive> section, the first argument is omitted and the local