<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
[
  <!ENTITY % BOOK_ENTITIES SYSTEM "../../User_Guide.ent">
  %BOOK_ENTITIES;
]>
<chapter id="java.AS7config">
  <title id="java.AS7config.title">AS7 modcluster subsystem Configuration</title>
  
  <section id="ModClusterSubSystem">
    <title>ModCluster Subsystem in JBoss AS7</title>
    <para>The mod_cluster integration is done via the modcluster subsystem. In AS7 only 1.1.x and later is supported.</para>
  </section>
  <section id="ModClusterSubSystemMiniConfiguration">
    <title>ModCluster Subsystem minimal configuration</title>
    <para>The minimal configuration is having the modcluster <code>schemaLocation</code> in the <code>schemaLocation</code> list:
    <programlisting>urn:jboss:domain:modcluster:1.0 jboss-mod-cluster.xsd</programlisting>
    and the <code>extension module</code> in the <code>extensions</code> list:
    <programlisting>&lt;extension module="org.jboss.as.modcluster"/&gt;</programlisting>
    and <code>subsystem</code> declaration like:
    <programlisting>&lt;subsystem xmlns="urn:jboss:domain:modcluster:1.0"/&gt;</programlisting>
    With that configuration modcluster will listen for advertise on <code>224.0.1.105:23364</code> use the <code>simple-load-provider</code> with
    a load factor of 1.
    </para>
   </section>
  <section id="ModClusterSubSystemConfiguration">
    <title>ModCluster Subsystem configuration</title>
    <section id="AS7ModClusterConfig">
       <title>mod-cluster-config Attributes</title> 
       <para>The attributs correspond to the <link linkend="java.properties">properties</link>
       </para>
       <para>Proxy Discovery Configuration</para>
     <informaltable frame="all">
     <tgroup cols="3">
        <thead>
          <row>
            <entry>Attribute</entry>
            <entry>Property</entry>
            <entry>Default</entry>
           </row>
        </thead>
        <tbody>
          <row>
            <entry>proxy-list</entry>
            <entry>proxyList</entry>
            <entry><emphasis>None</emphasis></entry>
          </row>
          <row>
            <entry>proxy-url</entry>
            <entry>proxyURL</entry>
            <entry><emphasis>None</emphasis></entry>
          </row>
          <row>
            <entry>advertise</entry>
            <entry>advertise</entry>
            <entry><emphasis>true</emphasis></entry>
          </row>
          <row>
            <entry>advertise-security-key</entry>
            <entry>advertiseSecurityKey</entry>
            <entry><emphasis>None</emphasis></entry>
          </row>
          <row>
            <entry>excluded-contexts</entry>
            <entry>excludedContexts</entry>
            <entry><emphasis>None</emphasis></entry>
          </row>
          <row>
            <entry>auto-enable-contexts</entry>
            <entry>autoEnableContexts</entry>
            <entry><emphasis>true</emphasis></entry>
          </row>
          <row>
            <entry>stop-context-timeout</entry>
            <entry>stopContextTimeout</entry>
            <entry><emphasis>10 seconds (in seconds)</emphasis></entry>
          </row>
          <row>
            <entry>socket-timeout</entry>
            <entry>nodeTimeout</entry>
            <entry><emphasis>20 seconds (in milli seconds)</emphasis></entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
    <para>Proxy Configuration</para>
    <informaltable frame="all">
     <tgroup cols="3">
        <thead>
          <row>
            <entry>Attribute</entry>
            <entry>Property</entry>
            <entry>Default</entry>
           </row>
        </thead>
        <tbody>
          <row>
            <entry>sticky-session</entry>
            <entry>stickySession</entry>
            <entry><emphasis>true</emphasis></entry>
          </row>
          <row>
            <entry>sticky-session-remove</entry>
            <entry>stickySessionRemove</entry>
            <entry><emphasis>false</emphasis></entry>
          </row>
          <row>
            <entry>sticky-session-force</entry>
            <entry>stickySessionForce</entry>
            <entry><emphasis>true</emphasis></entry>
          </row>
          <row>
            <entry>node-timeout</entry>
            <entry>workerTimeout</entry>
            <entry><emphasis>-1</emphasis></entry>
          </row>
          <row>
            <entry>max-attempts</entry>
            <entry>maxAttempts</entry>
            <entry><emphasis>1</emphasis></entry>
          </row>
          <row>
            <entry>flush-packets</entry>
            <entry>flushPackets</entry>
            <entry><emphasis>false</emphasis></entry>
          </row>
          <row>
            <entry>flush-wait</entry>
            <entry>flushWait</entry>
            <entry><emphasis>-1</emphasis></entry>
          </row>
          <row>
            <entry>ping</entry>
            <entry>ping</entry>
            <entry><emphasis>10</emphasis></entry>
          </row>
          <row>
            <entry>smax</entry>
            <entry>smax</entry>
            <entry><emphasis>-1</emphasis> it uses default value</entry>
          </row>
          <row>
            <entry>ttl</entry>
            <entry>ttl</entry>
            <entry><emphasis>-1</emphasis> it uses default value</entry>
          </row>
          <row>
            <entry>domain</entry>
            <entry>loadBalancingGroup</entry>
            <entry><emphasis>None</emphasis></entry>
          </row>
          <row>
            <entry>load-balancing-group</entry>
            <entry>loadBalancingGroup</entry>
            <entry><emphasis>None</emphasis></entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
    <para>SSL Configuration</para>
    <para>SSL configuration part needs to be added here too</para>

    </section>
    <section id="SimpleLoadProvider">
     <title>simple-load-provider Attributes</title>
     <para>The simple load provider always send the same load factor. That is the default one. Example:</para>
     <programlisting>
&lt;subsystem xmlns="urn:jboss:domain:modcluster:1.0"&gt;
  &lt;mod-cluster-config&gt;
    &lt;simple-load-provider factor="1"/&gt;
  &lt;/mod-cluster-config&gt;
&lt;/subsystem&gt;
     </programlisting>
     
     <informaltable frame="all">
     <tgroup cols="3">
        <thead>
          <row>
            <entry>Attribute</entry>
            <entry>Property</entry>
            <entry>Default</entry>
           </row>
        </thead>
        <tbody>
          <row>
            <entry>factor</entry>
            <entry>LoadBalancerFactor</entry>
            <entry><emphasis>1</emphasis></entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
    </section>
    <section id="DynamicLoadProvider">
       <title>dynamic-load-provider Attributes</title>
       <para>The dynamic load provide allows to have <code>load-metric</code> as well as <code>custom-load-metric</code> defined. For example:</para>
     <programlisting>
&lt;subsystem xmlns="urn:jboss:domain:modcluster:1.0"&gt;
  &lt;mod-cluster-config advertise-socket="mod_cluster"&gt;
    &lt;dynamic-load-provider history="10" decay="2"&gt;
       &lt;load-metric type="cpu" weight="2" capacity="1"/&gt;
       &lt;load-metric type="sessions" weight="1" capacity="512"/&gt;
       &lt;custom-load-metric class="mypackage.myclass" weight="1" capacity="512"&gt;
          &lt;property name="myproperty" value="myvalue" /&gt;
          &lt;property name="otherproperty" value="othervalue" /&gt;
       &lt;/custom-load-metric&gt;
    &lt;/dynamic-load-provider&gt;
  &lt;/mod-cluster-config&gt;
&lt;/subsystem&gt;
     </programlisting>
     <informaltable frame="all">
     <tgroup cols="3">
        <thead>
          <row>
            <entry>Attribute</entry>
            <entry>Property</entry>
            <entry>Default</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>history</entry>
            <entry>history</entry>
            <entry>512</entry>
          </row>
          <row>
            <entry>decay</entry>
            <entry>decayFactor</entry>
            <entry>512</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
    </section>
    <section id="LoadMetric">
     <title>load-metric Configuration</title>
     <para>The load-metric are the "classes" collecting information to allow computation of the load factor sent to httpd</para>
     <informaltable frame="all">
     <tgroup cols="3">
        <thead>
          <row>
            <entry>Attribute</entry>
            <entry>Property</entry>
            <entry>Default</entry>
           </row>
        </thead>
        <tbody>
          <row>
            <entry>type</entry>
            <entry>A Server-Side Load Metrics</entry>
            <entry><emphasis>Mandatory</emphasis></entry>
          </row>
          <row>
            <entry>weight</entry>
            <entry>weight</entry>
            <entry><emphasis>9</emphasis></entry>
          </row>
          <row>
            <entry>capacity</entry>
            <entry>capacity</entry>
            <entry><emphasis>512</emphasis></entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
    <section id="CustomLoadMetricType">
      <title>Supported load metric types</title>
     <informaltable frame="all">
     <tgroup cols="2">
        <thead>
          <row>
            <entry>type</entry>
            <entry>Corresponding Server-Side Load Metric</entry>
           </row>
        </thead>
        <tbody>
          <row>
            <entry>cpu</entry>
            <entry><link linkend="AverageSystemLoadMetric">AverageSystem</link>LoadMetric</entry>
          </row>
          <row>
            <entry>mem</entry>
            <entry><link linkend="SystemMemoryUsageLoadMetric">SystemMemoryUsage</link>LoadMetric</entry>
          </row>
          <row>
            <entry>heap</entry>
            <entry><link linkend="HeapMemoryUsageLoadMetric">HeapMemoryUsage</link>LoadMetric</entry>
          </row>
          <row>
            <entry>sessions</entry>
            <entry><link linkend="ActiveSessionsLoadMetric">ActiveSessions</link>LoadMetric</entry>
          </row>
          <row>
            <entry>requests</entry>
            <entry><link linkend="RequestCountLoadMetric">RequestCount</link>LoadMetric</entry>
          </row>
          <row>
            <entry>send-traffic</entry>
            <entry><link linkend="SendTrafficLoadMetric">SendTraffic</link>LoadMetric</entry>
          </row>
          <row>
            <entry>receive-traffic</entry>
            <entry><link linkend="ReceiveTrafficLoadMetric">ReceiveTraffic</link>LoadMetric</entry>
          </row>
          <row>
            <entry>busyness</entry>
            <entry><link linkend="BusyConnectorsLoadMetric">BusyConnectors</link>LoadMetric</entry>
          </row>
          <row>
            <entry>connection-pool</entry>
            <entry><link linkend="ConnectionPoolUsageLoadMetric">ConnectionPoolUsage</link>LoadMetric</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
    </section>
       
    </section>
    <section id="CustomLoadMetric">
     <title>custom-load-metric Configuration</title>
     <para>The custom-load-metric are for user defined "classes" collecting information. They are like the load-metric except <code>type</code>
           is replaced by <code>class</code>:</para>
     <informaltable frame="all">
     <tgroup cols="3">
        <thead>
          <row>
            <entry>Attribute</entry>
            <entry>Property</entry>
            <entry>Default</entry>
           </row>
        </thead>
        <tbody>
          <row>
            <entry>class</entry>
            <entry>Name of your class</entry>
            <entry><emphasis>Mandatory</emphasis></entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>

    </section>
    
    <section id="UsingJBossConsole">
     <title>load-metric Configuration with the jboss admin console</title>
     <para>The load-metric have 4 commands to add / remove metrics</para>
     <section id="AddMetric">
       <title>add-metric</title>
       <para>Allows to add a <code>load-metric</code> to the <code>dynamic-load-provider</code></para>
       <para>For example:</para>
       <programlisting>
       ./:add-metric(type=cpu, weight=2, capacity=1)
       </programlisting>
     </section>
       
     <section id="RemoveMetric">
       <title>remove-metric</title>
       <para>Allows to remove a <code>load-metric</code> from the <code>dynamic-load-provider</code></para>
       <para>For example:</para>
       <programlisting>
       ./:remove-metric(type=cpu)
       </programlisting>
     </section>

     <section id="AddCustomMetric">
       <title>add-custom-metric</title>
       <para>Allows to add a <code>load-custom-metric</code> to the <code>dynamic-load-provider</code></para>
       <para>For example:</para>
       <programlisting>
       ./:add-custom-metric(class=myclass, weight=2, capacity=1, property=[("pool" => "mypool"), ("var" => "myvariable")])
       </programlisting>
     </section>

     <section id="RemoveCustomMetric">
       <title>remove-custom-metric</title>
       <para>Allows to remove a <code>load-custom-metric</code> from the <code>dynamic-load-provider</code></para>
       <para>For example:</para>
       <programlisting>
       ./:remove-custom-metric(class=myclass)
       </programlisting>
     </section>
    </section>
  </section>
</chapter>
