[jboss-cvs] JBossAS SVN: r100686 - projects/docs/enterprise/5.0/mod_cluster/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Mon Feb 8 02:09:41 EST 2010
Author: gmeintjes
Date: 2010-02-08 02:09:41 -0500 (Mon, 08 Feb 2010)
New Revision: 100686
Modified:
projects/docs/enterprise/5.0/mod_cluster/en-US/Book_Info.xml
projects/docs/enterprise/5.0/mod_cluster/en-US/QuickStartGuide.xml
projects/docs/enterprise/5.0/mod_cluster/en-US/Revision_History.xml
Log:
Ammend to incorporate review comments.
Modified: projects/docs/enterprise/5.0/mod_cluster/en-US/Book_Info.xml
===================================================================
--- projects/docs/enterprise/5.0/mod_cluster/en-US/Book_Info.xml 2010-02-08 06:57:04 UTC (rev 100685)
+++ projects/docs/enterprise/5.0/mod_cluster/en-US/Book_Info.xml 2010-02-08 07:09:41 UTC (rev 100686)
@@ -7,7 +7,7 @@
<productname>JBoss Enterprise Application Platform</productname>
<productnumber>5.0</productnumber>
<edition>1</edition>
- <pubsnumber>1.7</pubsnumber>
+ <pubsnumber>1.8</pubsnumber>
<abstract>
<para>
mod_cluster is an httpd-based load balancer that uses a
Modified: projects/docs/enterprise/5.0/mod_cluster/en-US/QuickStartGuide.xml
===================================================================
--- projects/docs/enterprise/5.0/mod_cluster/en-US/QuickStartGuide.xml 2010-02-08 06:57:04 UTC (rev 100685)
+++ projects/docs/enterprise/5.0/mod_cluster/en-US/QuickStartGuide.xml 2010-02-08 07:09:41 UTC (rev 100686)
@@ -4,7 +4,7 @@
<chapter id="chap-mod_cluster-Quick_Start_Guide">
<title>Quick Start Guide</title>
<para>
- The following steps are required to set up a minimal working installation of mod_cluster on a single httpd server and a single back end server, either <application>JBoss EAP</application>, <application>JBossWeb</application> or <application>Tomcat</application>. The steps can be repeated to add as many httpd servers or back end servers to your cluster as desired.
+ The following steps are required to set up a minimal working installation of mod_cluster on a single <application>httpd</application> server and a single back end server, either <application>JBoss EAP</application>, <application>JBossWeb</application> or <application>Tomcat</application>. The steps can be repeated to add as many httpd servers or back end servers to your cluster as desired.
</para>
<para>
The steps shown here are not intended to demonstrate how to set up a production install of mod_cluster; for example using <application>SSL</application> to secure access to the httpd-side mod_manager component is not covered. See the <citetitle>httpd-side</citetitle> and <citetitle>Java-side configuration documentation</citetitle> for the full set of configuration options.
@@ -12,7 +12,7 @@
<section id="sect-mod_cluster-Quick_Start_Guide-Download_mod_cluster_components">
<title>Download mod-cluster components</title>
<para>
- Download the latest httpd and Java release bundles.
+ Download the latest httpd and <application>Java</application> release bundles.
</para>
<!-- <para>
If there is no pre-built httpd bundle appropriate for your OS or system architecture, you can build the binary from source.
@@ -21,7 +21,7 @@
<formalpara>
<title>mod_proxy configuration</title>
<para>
- mod_proxy directives, such as ProxyIOBufferSize, could be used to configure mod_cluster. There is no need to use ProxyPass directives because mod_cluster automatically configures which URLs have to be forwarded to JBossWEB.
+ mod_proxy directives, such as <command>ProxyIOBufferSize</command>, could be used to configure mod_cluster. There is no need to use <command>ProxyPass</command> directives because mod_cluster automatically configures which URLs have to be forwarded to JBossWEB.
</para>
</formalpara>
@@ -43,40 +43,78 @@
<term>CreateBalancers</term>
<listitem>
<para>
- Define how the balancer are created in the httpd VirtualHosts, this is to allow directives like:
+ Define how the balancers are created in the <literal>httpd VirtualHosts</literal>, this is to allow directives such as the following:
+<screen>
+ProxyPass / balancer://mycluster1/
+</screen>
</para>
+ <para>
+<literallayout>Where:
+ 0: Create in all <literal>VirtualHosts</literal> defined in <literal>httpd</literal>.
+ 1: Do not create balancers (requires at least one <varname>ProxyPass/ProxyPassMatch</varname> to define the balancer names).
+ 2: Create only the main server.
+ Default: 2
+</literallayout>
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term>UseAlias</term>
<listitem>
<para>
- Check that the Alias corresponds to the ServerName (See Host Name Aliases)
+ Check that the <filename>Alias</filename> corresponds to the <filename>ServerName</filename> (See Host Name Aliases).
</para>
+ <para>
+<literallayout>Where:
+ 0: Do not (ignore Aliases)
+ 1: Check it
+ 2: Default: 0 Ignore the Alias information from the nodes.
+ </literallayout>
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term>LBstatusRecalTime </term>
<listitem>
<para>
- Time interval in seconds for loadbalancing logic to recalculate the status of a node: (Default: 5 seconds)
+ Time interval in seconds for <varname>loadbalancing</varname> logic to recalculate the status of a node: (Default: 5 seconds)
</para>
+ <para>
+ The actual formula to recalculate the status of a node is:
+ </para>
+<programlisting>
+status = lbstatus + (elected - oldelected) * 1000)/lbfactor;
+</programlisting>
+ <para>
+<varname>lbfactor</varname> is received for the node via STATUS messages.
+ </para>
+ <para>
+<varname>lbstatus</varname> is recalculated every <varname>LBstatusRecalTime</varname> seconds using the formula:
+ </para>
+<programlisting>
+lbstatus = (elected - oldelected) * 1000)/lbfactor;
+</programlisting>
+<literallayout>Where:
+ <varname>elected</varname> is the number of times the worker was elected.
+ <varname>oldelected</varname> is elected last time the <varname>lbstatus</varname> was recalculated.
+ The node with the lowest status is selected. Nodes with <varname>lbfactor</varname> ≤ 0 are skipped by the calculation logic.
+ </literallayout>
</listitem>
</varlistentry>
<varlistentry>
<term>ProxyPassMatch/ProxyPass </term>
<listitem>
<para>
- ProxyPassMatch and ProxyPass are mod_proxy directives that when using ! (instead of the back-end url) prevent to reverse-proxy in the path.
+ <command>ProxyPassMatch</command> and <command>ProxyPass</command> are mod_proxy directives that when using ! (instead of the back-end url), prevent to reverse-proxy in the path.
</para>
<para>
- This could be used allow httpd to serve static information like images.
+ This could be used allow httpd to serve static information, such as images.
</para>
<programlisting>
ProxyPassMatch ^(/.*\.gif)$ !
</programlisting>
<para>
- The above, for example, will allow httpd to directly server the .gif files.
+ The above, for example, will allow httpd to directly serve the <filename>.gif</filename> files.
</para>
</listitem>
@@ -93,7 +131,7 @@
<term>MemManagerFile</term>
<listitem>
<para>
- That is the base name for the names mod_manager will use to store configuration, generate keys for shared memory or lock files. That must be an absolute path name; the directories will created if needed. It is highly recommended that those files are placed on a local drive and not an NFS share. Default: $server_root/logs/
+ <filename>MemManagerFile</filename> is the base name for the names that mod_manager will use to store configuration, generate keys for shared memory or lock files. That must be an absolute path name; the directories will be created if needed. It is highly recommended that those files are placed on a local drive and not an NFS share. Default: <filename class='directory'>$server_root/logs/</filename>
</para>
</listitem>
</varlistentry>
@@ -101,7 +139,7 @@
<term>Maxnode</term>
<listitem>
<para>
- That is the number max nodes supported by mod_cluster. Default: 20
+ <literal>Maxnode</literal> is the maximum number of nodes supported by mod_cluster. Default: 20
</para>
</listitem>
</varlistentry>
@@ -109,7 +147,7 @@
<term>Maxhost</term>
<listitem>
<para>
- That is the number max host (Aliases) supported by mod_cluster. That is also the max number of balancers. Default: 10
+ <literal>Maxhost</literal> is the maximum number of hosts (Aliases) supported by mod_cluster. It is also the maximum number of balancers. Default: 10
</para>
</listitem>
</varlistentry>
@@ -117,7 +155,7 @@
<term>Maxsessionid</term>
<listitem>
<para>
- That is the number of active sessionid we store to give number of active sessions in the mod_cluster-manager handler. A session is unactive when mod_cluster doesn't receive any information from the session in 5 minutes. Default: 0 (the logic is activated).
+ <literal>Maxsessionid</literal> is the number of active <varname>sessionid</varname> we store to give a number of active sessions in the mod_cluster-manager handler. A session is inactive when mod_cluster does not receive any information from the session in 5 minutes. Default: 0 (the logic is activated).
</para>
</listitem>
</varlistentry>
@@ -125,7 +163,7 @@
<term>ManagerBalancerName</term>
<listitem>
<para>
- That is the name of balancer to use when the JBoss AS/JBossWeb/Tomcat doesn't provide a balancer name. That is not supported in the current version. (Default value is used). Default: mycluster
+ <filename>ManagerBalancerName</filename> is the name of balancer to use when the JBoss AEP/JBossWeb/Tomcat doesn't provide a balancer name. That is not supported in the current version. (Default value is used). Default: <filename>mycluster</filename>
</para>
</listitem>
</varlistentry>
@@ -133,7 +171,7 @@
<term>PersistSlots</term>
<listitem>
<para>
- Tell mod_slotmem to persist the nodes, Alias and Context in files. Default: Off
+ Tell <literal>mod_slotmem</literal> to persist the nodes, Alias and Context in files. Default: Off
</para>
</listitem>
</varlistentry>
@@ -141,7 +179,7 @@
<term>SetHandler mod_cluster-manager</term>
<listitem>
<para>
- That is the handler to display the node mod_cluster sees from the cluster. It displays the information about the nodes like INFO and additionaly counts the number of active sessions.
+ That is the handler to display the node mod_cluster sees from the cluster. It displays the information about the nodes like <varname>INFO</varname> and additionaly counts the number of active sessions.
</para>
<programlisting><![CDATA[
<Location /mod_cluster-manager>
@@ -162,7 +200,7 @@
<term>Transferred</term>
<listitem>
<para>
- Corresponds to the POST data sent to the back-end server.
+ Corresponds to the <varname>POST</varname> data sent to the back-end server.
</para>
</listitem>
</varlistentry>
@@ -178,25 +216,17 @@
<term>sessions</term>
<listitem>
<para>
- Corresponds to the number of sessions mod_cluster report as active (on which there was a request during the past 5 minutes). That field is not present when Maxsessionid is zero.
+ Corresponds to the number of sessions mod_cluster report as active (on which there was a request during the past 5 minutes). That field is not present when <varname>Maxsessionid</varname> is zero.
</para>
</listitem>
</varlistentry>
</variablelist>
</note>
-
-
-
-
-
-
-
-
<formalpara>
<title>mod_advertise</title>
<para>
- mod_advertise uses multicast packets to advertise the VirtualHost where it is configured that must be the same VirtualHost where mod_manager is defined. Of course at least one mod_advertise must be in the VirtualHost to allow mod_cluster to find the right IP and port to give to the ClusterListener.
+ <varname>mod_advertise</varname> uses multicast packets to advertise the <literal>VirtualHost</literal> where it is configured that must be the same VirtualHost where mod_manager is defined. At least one <varname>mod_advertise</varname> must be in the VirtualHost to allow mod_cluster to find the right IP and port to provide to the ClusterListener.
</para>
</formalpara>
<variablelist>
@@ -212,7 +242,7 @@
<term>ServerAdvertise On http://hostname:port</term>
<listitem>
<para>
- Tell the hostname and port to use. Only needed if the VirtualHost is not defined correctly, if the VirtualHost is a Name-based Virtual Host or when VirtualHost is not used.
+ Advise the hostname and port to use. Only needed if the <filename>VirtualHost</filename> is not defined correctly, if the <filename>VirtualHost</filename> is a Name-based Virtual Host or when <filename>VirtualHost</filename> is not used.
</para>
</listitem>
</varlistentry>
@@ -220,7 +250,7 @@
<term>ServerAdvertise Off</term>
<listitem>
<para>
- Don't use the advertise mechanism. Default: On.
+ Do not use the advertise mechanism. Default: On.
</para>
</listitem>
</varlistentry>
@@ -228,7 +258,7 @@
<term>AdvertiseGroup IP:port </term>
<listitem>
<para>
- That is the multicast address to use (something like 232.0.0.2:8888 for example). IP should correspond to AdvertiseGroupAddress and port to AdvertisePort in the JBoss EAP/JBossWeb/Tomcat configuration. Note that if JBoss EAP is used and the -u startup switch is included in the EAP startup command, the default AdvertiseGroupAddress is the value passed via the -u. Default: 224.0.1.105:23364. If port is missing the default port will be used: 23364.
+ That is the multicast address to use (something like 232.0.0.2:8888 for example). IP should correspond to <varname>AdvertiseGroupAddress</varname> and port to <literal>AdvertisePort</literal> in the JBoss EAP/JBossWeb/Tomcat configuration. Note that if JBoss EAP is used and the <literal>-u</literal> startup switch is included in the EAP startup command, the default <varname>AdvertiseGroupAddress</varname> is the value passed via the <literal>-u</literal>. Default: 224.0.1.105:23364. If port is missing the default port will be used: 23364.
</para>
</listitem>
</varlistentry>
@@ -244,7 +274,7 @@
<term>AdvertiseSecurityKey value</term>
<listitem>
<para>
- key string to identify the mod_cluster in JBossWEB. Default: No default value. Information not sent.
+ The key string to identify the mod_cluster in JBossWEB. Default: No default value. Information not sent.
</para>
</listitem>
</varlistentry>
@@ -260,7 +290,7 @@
<term>AdvertiseBindAddress IP:port </term>
<listitem>
<para>
- That is the address and port httpd is bind to send the multicast messages. This allow to specify an address on multi IP address boxes. Default: 0.0.0.0:23364
+ It is the address and port httpd binds to send the multicast messages. This allows to specify an address on multi IP address boxes. Default: 0.0.0.0:23364
</para>
</listitem>
</varlistentry>
@@ -401,7 +431,7 @@
<section id="sect-mod_cluster-Quick_Start_Guide-Install_the_Java_side_binaries">
<title>Install the Java-side binaries</title>
<para>
- Extract the Java-side binary to a temporary directory. The following assumes it was extracted to <filename>/tmp/mod-cluster</filename>.
+ Extract the <classname>Java-side</classname> binary to a temporary directory. The following assumes it was extracted to <filename>/tmp/mod-cluster</filename>.
</para>
<para>
The next step depends on whether your target server is JBoss EAP or JBossWeb/Tomcat.
@@ -523,7 +553,7 @@
<formalpara id="form-mod_cluster-Start_the_back_end_server-Starting_JBoss_AS">
<title>Starting JBoss EAP</title>
<para>
- To start <application>JBoss AS</application> enter the following:
+ To start <application>JBoss EAP</application> enter the following:
</para>
</formalpara>
@@ -560,7 +590,7 @@
<formalpara>
<title>Overview of the Demo Application</title>
<para>
- The mod_cluster distribution includes a demo application that helps demonstrate how different server-side scenarios affect the routing of client requests by the load balancer. The demo application is located in the demo directory of the mod_cluster distribution.
+ The mod_cluster distribution includes a demo application that helps demonstrate how different server-side scenarios affect the routing of client requests by the load balancer. The demo application is located in the <filename class='directory'>demo</filename> directory of the mod_cluster distribution.
</para>
</formalpara>
<para>
@@ -568,11 +598,11 @@
<orderedlist>
<listitem>
<para>
- The first component is a war file that needs to be deployed in JBossWeb/Tomcat/JBoss AS. The war includes a number of servlets:
+ The first component is a <filename>war</filename> file that needs to be deployed in JBossWeb/Tomcat/JBoss EAP. The <filename>war</filename> includes a number of servlets:
<itemizedlist>
<listitem>
<para>
- A primary servlet that responds to client requests with the value of the jvmRoute attribute of the <filename>server.xml</filename> file's Engine element. This response allows the client application to track which servers are handling requests.<filename>mod_proxy.so</filename>
+ A primary servlet that responds to client requests with the value of the <varname>jvmRoute</varname> attribute of the <filename>server.xml</filename> file's Engine element. This response allows the client application to track which servers are handling requests.<filename>mod_proxy.so</filename>
</para>
</listitem>
<listitem>
@@ -585,10 +615,10 @@
</listitem>
<listitem>
<para>
- The second component is a GUI application that allows a user to launch a pool of threads that repeatedly make requests to the load balancer. The requests are ultimately routed to the demo war's primary servlet. The application tracks which servers are handling the requests and displays this information in a chart.
+ The second component is a GUI application that allows a user to launch a pool of threads that repeatedly make requests to the load balancer. The requests are ultimately routed to the demo <filename>war's</filename> primary servlet. The application tracks which servers are handling the requests and displays this information in a chart.
</para>
<para>
- The application can also send separate requests to the demo war's load generation servlets, allowing the user to see how different load conditions affect the balancing of requests.
+ The application can also send separate requests to the demo <filename>war's</filename> load generation servlets, allowing the user to see how different load conditions affect the balancing of requests.
</para>
</listitem>
</orderedlist>
@@ -614,12 +644,12 @@
<orderedlist>
<listitem>
<para>
- Unpack the mod_cluster distribution on your filesystem. Here we assume it has been unzipped to /home/bes/mod_cluster or C:\mod_cluster.
+ Unpack the mod_cluster distribution on your filesystem. Here we assume it has been unzipped to <filename class='directory'>/home/bes/mod_cluster</filename> or <filename class='directory'>C:\mod_cluster</filename>.
</para>
</listitem>
<listitem>
<para>
- Install mod_cluster into your httpd server as described at Installation of the httpd part.
+ Install mod_cluster into your httpd server as described in Installation of the httpd.
</para>
</listitem>
<listitem>
@@ -634,7 +664,7 @@
</listitem>
<listitem>
<para>
- Deploy the load-demo.war found in the distribution's demo/server folder to your JBossAS/JBossWeb/Tomcat servers.
+ Deploy the <filename>load-demo.war</filename> found in the distribution's <filename class='directory'>demo/server</filename>folder to your JBossEAP/JBossWeb/Tomcat servers.
</para>
</listitem>
<listitem>
@@ -666,43 +696,43 @@
</listitem>
<listitem>
<para>
- Configure the hostname and address of the httpd server, the number of client threads, etc and click the "Start" button. Refer to the Client Driver Configuration Options for details on the configuration options.
+ Configure the hostname and address of the httpd server, the number of client threads etc., and click the <guibutton>Start</guibutton> button. Refer to the Client Driver Configuration Options for details on the configuration options.
</para>
</listitem>
<listitem>
<para>
- Switch to the "Request Balancing" tab to see how many requests are going to each of your JBoss EAP/JBossWeb/Tomcat servers.
+ Switch to the Request Balancing tab to see how many requests are going to each of your JBoss EAP/JBossWeb/Tomcat servers.
</para>
</listitem>
<listitem>
<para>
- Switch to the "Session Balancing" tab to see how many active sessions2 are being hosted by each of your JBossAS/JBossWeb/Tomcat servers.
+ Switch to the "Session Balancing" tab to see how many active <literal>sessions2</literal> are being hosted by each of your JBossEAP/JBossWeb/Tomcat servers.
</para>
</listitem>
<listitem>
<para>
- Stop some of your JBoss EAP/JBossWeb/Tomcat servers and/or undeploy the load-demo.war from some of the servers and see the effect this has on load balancing.
+ Stop some of your JBoss EAP/JBossWeb/Tomcat servers and/or undeploy the <filename>load-demo.war</filename> from some of the servers and see the effect this has on load balancing.
</para>
</listitem>
<listitem>
<para>
- Restart some of your JBoss EAP/JBossWeb/Tomcat servers and/or re-deploy the load-demo.war to some of the servers and see the effect this has on load balancing.
+ Restart some of your JBoss EAP/JBossWeb/Tomcat servers and/or re-deploy the <filename>load-demo.war</filename> to some of the servers and see the effect this has on load balancing.
</para>
</listitem>
<listitem>
<para>
- Experiment with adding artificial load to one or more servers to see what effect that has on load balancing. See Load Generation Scenarios for details.
+ Experiment with adding artificial load to one or more servers to see what effect that has on load balancing.
</para>
</listitem>
</orderedlist>
<para>
- Most of the various panels in application interface also present information on the current status on any client threads. "Total Clients" is the number of client threads created since the last time the "Start" button was pushed. "Live Clients" is the number of threads currently running. "Failed Clients" is the number of clients that terminated abnormally; i.e. made a request that resulted in something other than an HTTP 200 response.
+ Most of the various panels in the application interface also present information on the current status on any client threads. "Total Clients" is the number of client threads created since the last time the "Start" button was pushed. "Live Clients" is the number of threads currently running. "Failed Clients" is the number of clients that terminated abnormally; i.e. made a request that resulted in something other than an HTTP 200 response.
</para>
<formalpara>
<title>Client Driver Configuration Options</title>
<para>
- The configuration of the client driver is done via the application's "Client Control" tab.
+ The configuration of the <classname>client driver</classname> is done via the application Client Control tab.
</para>
</formalpara>
<para>
@@ -713,7 +743,7 @@
<term>Proxy Hostname</term>
<listitem>
<para>
- Hostname of the load balancer or the IP address on which it is listening for requests.
+ <application>Hostname</application> of the load balancer or the IP address on which it is listening for requests.
</para>
</listitem>
</varlistentry>
@@ -735,7 +765,7 @@
<term>Session Life</term>
<listitem>
<para>
- Number of seconds a client thread should use a session before invalidating or abandoning it. Generally it is good to keep this to a small value; otherwise the use of session stickiness will prevent changes in server load from affecting the load balancer's routing decisions. With sticky sessions enabled (strongly recommended), it is the creation of a new session that allows the load balancer to try to balance load.
+ Number of seconds a client thread should use a session before invalidating or abandoning it. Generally it is good to keep this to a small value; otherwise the use of session stickiness will prevent changes in server load from affecting the load balancer routing decisions. With sticky sessions enabled (strongly recommended), it is the creation of a new session that allows the load balancer to try to balance load.
</para>
</listitem>
</varlistentry>
@@ -765,7 +795,7 @@
<term>Sleep Time</term>
<listitem>
<para>
- Number of ms the client threads should sleep between requests.
+ Number of <varname>ms</varname> the client threads should sleep between requests.
</para>
</listitem>
</varlistentry>
@@ -782,7 +812,7 @@
<formalpara>
<title>Load Generation Scenarios</title>
<para>
- You can use the application's GUI to instruct individual servers to artificially generate various types of load, and then track how that load affects request and session balancing. Load generation is controlled via the application's "Server Load Control" tab.
+ You can use the application GUI to instruct individual servers to artificially generate various types of load, and then track how that load affects request and session balancing. Load generation is controlled via the application Server Load Control tab.
</para>
</formalpara>
<para>
@@ -835,7 +865,7 @@
</listitem>
<listitem>
<para>
- Datasource Use: Generates server load by taking connections from the java:DefaultDS datasource for a period.
+ Datasource Use: Generates server load by taking connections from the <literal>java:DefaultDS</literal> datasource for a period.
</para>
</listitem>
<listitem>
Modified: projects/docs/enterprise/5.0/mod_cluster/en-US/Revision_History.xml
===================================================================
--- projects/docs/enterprise/5.0/mod_cluster/en-US/Revision_History.xml 2010-02-08 06:57:04 UTC (rev 100685)
+++ projects/docs/enterprise/5.0/mod_cluster/en-US/Revision_History.xml 2010-02-08 07:09:41 UTC (rev 100686)
@@ -6,7 +6,7 @@
<simpara>
<revhistory>
<revision>
- <revnumber>1.7</revnumber>
+ <revnumber>1.8</revnumber>
<date>Fri 05 Feb 2010</date>
<author>
<firstname>Gary</firstname>
More information about the jboss-cvs-commits
mailing list