<?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="native.config">
  <title>httpd configuration</title>

  <section>
    <title>Apache httpd configuration</title>

    <para>You need to load the modules that are needed for mod_cluster for
    example:<programlisting>LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_ajp_module modules/mod_proxy_ajp.so
LoadModule slotmem_module modules/mod_slotmem.so
LoadModule manager_module modules/mod_manager.so
LoadModule proxy_cluster_module modules/mod_proxy_cluster.so
LoadModule advertise_module modules/mod_advertise.so</programlisting></para>

    <para>mod_proxy and mod_proxy_ajp are standard httpd modules. mod_slotmem
    is a shared slotmem memory provider. mod_manager is the module that reads
    information from JBoss AS/JBossWeb/Tomcat and updates the shared memory
    information. mod_proxy_cluster is the module that contains the balancer
    for mod_proxy. mod_advertise is an additional module that allows httpd to
    advertise via multicast packets the IP and port where the mod_cluster is
    listening. This multi-module architecture allows the modules to easily be
    changed depending on what the customer wants to do. For example when using
    http instead of AJP, only</para>

    <para><programlisting>LoadModule proxy_ajp_module modules/mod_proxy_ajp.so</programlisting></para>

    <para>needs to be changed to:</para>

    <para><programlisting>LoadModule proxy_http_module modules/mod_proxy_http.so</programlisting></para>
  </section>

  <section>
    <title>mod_proxy configuration</title>

    <para>mod_proxy directives like 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.</para>
  </section>

  <section>
    <title>mod_slotmem configuration</title>

    <para>The actual version doesn't require any configuration
    directives.</para>
  </section>

  <section>
    <title>mod_proxy_cluster</title>

    <section><title>CreateBalancers</title>
    <para>CreateBalancers: Define how the balancer are created in the httpd
    VirtualHosts, this is to allow directives like:</para>

    <para><programlisting>ProxyPass / balancer://mycluster1/</programlisting></para>

    <para>0: Create in all VirtualHosts defined in httpd.</para>

    <para>1: Don't create balancers (requires at least one
    ProxyPass/ProxyPassMatch to define the balancer names).</para>

    <para>2: Create only the main server.</para>

    <para>Default: 2</para>

    <para><emphasis>Note:</emphasis> When using 1 don't forget to configure
    the balancer in the ProxyPass directive, because the default is empty
    stickysession and nofailover=Off and the values received via the MCMP
    CONFIG message are ignored.</para>
    </section>

    <section><title>UseAlias</title>
    <para>UseAlias: Check that the Alias corresponds to the ServerName (See
    <ulink
    url="http://labs.jboss.com/file-access/default/members/jbossweb/freezone/docs/latest/config/host.html">Host
    Name Aliases</ulink>)</para>
    <para>Off: Don't check (ignore Aliases)</para>
    <para>On: Check aliases</para>
    <para>Default: Off Ignore the Alias information from the nodes.</para>
    <para><emphasis>Versions older than 1.3.1.Final only accept values 0 and 1 respectively.</emphasis></para>
    </section>

    <section><title>LBstatusRecalTime</title>
    <para>LBstatusRecalTime: Time interval in seconds for loadbalancing logic to recalculate the
    status of a node</para>
    <para>Default: 5 seconds</para>

    <para>The actual formula to recalculate the status of a node is:</para>

    <para><programlisting>status = lbstatus + (elected - oldelected) * 1000)/lbfactor;</programlisting></para>

    <para>lbfactor is received for the node via STATUS messages.lbstatus is
    recalculated every LBstatusRecalTime seconds using the formula:</para>

    <para><programlisting>lbstatus = (elected - oldelected) * 1000)/lbfactor;</programlisting></para>

    <para>elected is the number of time the worker was elected.oldelected is
    elected last time the lbstatus was recalculated.The node with the lowest
    status is selected. Nodes with lbfactor ≤ 0 are skipped by the both
    calculation logic.</para>
    </section>

    <section><title>WaitForRemove</title>
    <para>WaitForRemove: Time in seconds before a removed node is forgotten by httpd</para>
    <para>Default: 10 seconds</para>
    </section>

    <section><title>ProxyPassMatch/ProxyPass</title>
    <para>ProxyPassMatch/ProxyPass: ProxyPassMatch and ProxyPass are mod_proxy
    directives that when using ! (instead the back-end url) prevent to
    reverse-proxy in the path.
    This could be used allow httpd to serve static
    information like images.</para>

    <para><programlisting>ProxyPassMatch ^(/.*\.gif)$ !  </programlisting></para>

    <para>The above for example will allow httpd to server directly the .gif
    files.</para>
    </section>

    <section>
      <title>EnableOptions</title>
      <para>
        Use OPTIONS method to periodically check the active connection.
        Fulfils the same role as the CPING/CPONG used by AJP but for HTTP/HTTPS connections.
        The endpoint needs to implement at least HTTP/1.1.
      </para>

      <para>On (or no value): Use OPTIONS (default)</para>
      <para>Off: Don't use OPTIONS</para>
    </section>
  </section>

  <section>
    <title>mod_manager</title>

    <para>The Context of a mod_manger directive is VirtualHost except mentioned otherwise.
          <code>server config</code> means that it must be outside a VirtualHost configuration.
          If not an error message will be displayed and httpd won't start.
    </para>

    <section id="EnableMCPMReceive">
    <title>EnableMCPMReceive</title>
    <para>EnableMCPMReceive - Allow the VirtualHost to receive MCPM.
    Allow the VirtualHost to receive the MCPM from the nodes. You need
    one EnableMCPMReceive in your httpd configuration to allow mod_cluster
    to work, put it in the VirtualHost where you configure advertise.
    </para>
    </section>
    
    <section><title>MemManagerFile</title>
    <para>MemManagerFile: 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. (Context: server config)</para>
    <para>Default: $server_root/logs/</para>
    </section>

    <section><title>Maxcontext</title>
    <para>Maxcontext: That is the number max of contexts supported by
    mod_cluster. (Context: server config)</para>
    <para>Default: 100</para>
    </section>

    <section><title>Maxnode</title>
    <para>Maxnode: That is the number max nodes supported by mod_cluster.
          (Context: server config)</para>
    <para>Default: 20</para>
    </section>

    <section><title>Maxhost</title>
    <para>Maxhost: That is the number max host (Aliases) supported by
    mod_cluster. That is also the max number of balancers.
    (Context: server config)</para>
    <para>Default: 20</para>
    </section>

    <section><title>Maxsessionid</title>
    <para>Maxsessionid: 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. (Context: server config)</para>
    <para>Default: 0 (the logic is not activated).</para>
    </section>

    <section><title>MaxMCMPMaxMessSize</title>
    <para>MaxMCMPMaxMessSize:  Maximum size of MCMP messages.
     from other Max directives.</para>
    <para>Default: calculated from other Max directives. Min: 1024</para>
    </section>

    <section><title>ManagerBalancerName</title>
    <para>ManagerBalancerName: That is the name of balancer to use when the
    JBoss AS/JBossWeb/Tomcat doesn't provide a balancer name.</para>
    <para>Default: mycluster</para>
    </section>

    <section><title>PersistSlots</title>
    <para>PersistSlots: Tell mod_slotmem to persist the nodes, Alias and
    Context in files. (Context: server config)</para>
    <para>Default: Off</para>
    </section>

    <section><title>CheckNonce</title>
    <para>CheckNonce: Switch check of nonce when using mod_cluster-manager
    handler on | off Since 1.1.0.CR1</para>
    <para>Default: on Nonce checked</para>
    </section>

    <section><title>AllowDisplay</title>
    <para>AllowDisplay: Switch additional display on mod_cluster-manager main page
    on | off Since 1.1.0.GA</para>
    <para>Default: off Only version displayed</para>
    </section>

    <section><title>AllowCmd</title>
    <para>AllowCmd: Allow commands using mod_cluster-manager URL
     on | off Since 1.1.0.GA</para>
    <para>Default: on Commmands allowed</para>
    </section>

    <section><title>ReduceDisplay</title>
    <para>ReduceDisplay - Reduce the information the main mod_cluster-manager page to allow more nodes in the page.
     on | off</para>
    <para>Default: off Full information displayed</para>
    </section>

    <section id="SetHandlermod_cluster-manager">
    <title>SetHandler mod_cluster-manager</title>
    <para>SetHandler mod_cluster-manager: 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.</para>

    <para><programlisting>&lt;Location /mod_cluster_manager&gt;
SetHandler mod_cluster-manager
Order deny,allow
Deny from all
Allow from 127.0.0.1
&lt;/Location&gt;</programlisting></para>

    <para>When accessing the location you define in httpd.conf you get
    something like: <mediaobject>
        <imageobject role="mod_cluster status">
          <imagedata align="center" fileref="images/mod_status.jpg"
                     format="JPG" />
        </imageobject>
      </mediaobject></para>

    <para> </para>

    <para>Note that:</para>

    <para>Transferred: Corresponds to the POST data send to the back-end
    server.</para>

    <para>Connected: Corresponds to the number of requests been processed when
    the mod_cluster status page was requested.</para>

    <para>sessions: 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.</para>
    </section>
  </section>

  <section id="mod_advertise">
    <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.</para>

    <section><title>ServerAdvertise</title>
    <para>ServerAdvertise On: Use the advertise mechanism to tell the JBoss
    AS/JBossWeb/Tomcat to whom it should send the cluster
    information.</para>
    <para>ServerAdvertise On http://hostname:port: Tell the hostname and
    port to use. Only needed if the VirtualHost is not defined correctly, if
    the VirtualHost is a <ulink
    url="http://httpd.apache.org/docs/2.2/vhosts/name-based.html">Name-based
    Virtual Host</ulink> or when VirtualHost is not used.</para>
    <para>ServerAdvertise Off: Don't use the advertise mechanism.</para>
    <para>Default: Off. (Any Advertise directive in a VirtualHost sets it to On in the VirtualHost)</para>
    </section>

    <section><title>AdvertiseGroup</title>
    <para>AdvertiseGroup IP:port: 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
    AS/JBossWeb/Tomcat configuration. Note that if JBoss AS is used and the -u
    startup switch is included in the AS startup command, the default
    AdvertiseGroupAddress is the value passed via the -u.
    If port is missing the default port will be used: 23364.</para>
    <para>Default: 224.0.1.105:23364.</para>
    </section>

    <section><title>AdvertiseFrequency</title>
    <para>AdvertiseFrequency seconds[.miliseconds]: Time between the multicast
    messages advertising the IP and port.</para>
    <para>Default: 10 Ten seconds.</para>
    </section>

    <section><title>AdvertiseSecurityKey</title>
    <para>AdvertiseSecurityKey value: key string used to verify advertisements checksums.
    If configured on either side the verification is required. Both sides must use the 
    same security key.</para>
    <para>Default: No default value.</para>
    </section>

    <section><title>AdvertiseManagerUrl</title>
    <para>AdvertiseManagerUrl value: Not used in this version (It is sent in
    the X-Manager-Url: value header). That is the URL that JBoss
    AS/JBossWeb/Tomcat should use to send information to mod_cluster</para>
    <para>Default: No default value. Information not sent.</para>
    </section>

    <section><title>AdvertiseBindAddress</title>
    <para>AdvertiseBindAddress IP:port: 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.</para>
    <para>Default: 0.0.0.0:23364</para>
    </section>
  </section>

  <section id="MinimalExample">
    <title>Minimal Example</title>

    <para><programlisting>LoadModule proxy_module modules/mod_proxy.so
 LoadModule proxy_ajp_module modules/mod_proxy_ajp.so
 LoadModule slotmem_module modules/mod_slotmem.so
 LoadModule manager_module modules/mod_manager.so
 LoadModule proxy_cluster_module modules/mod_proxy_cluster.so
 LoadModule advertise_module modules/mod_advertise.so
 
 Listen 10.33.144.3:6666
 &lt;VirtualHost 10.33.144.3:6666&gt;
 
   &lt;Location /&gt;
      Order deny,allow
      Deny from all
      Allow from 10.33.144.
   &lt;/Location&gt;
 
 KeepAliveTimeout 60
 MaxKeepAliveRequests 0
 
 ManagerBalancerName mycluster
 ServerAdvertise On
 EnableMCPMReceive
 
 &lt;/VirtualHost&gt;</programlisting></para>
  </section>
</chapter>
