<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE chapter 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="faq">
  <title>Frequently Asked questions</title>

  <section id="advertisemessage">
    <title>What is Advertise</title>
    <para>
      Advertise allows autodiscovery of httpd proxies by the cluster nodes.
      It is done by sending multicast messages from httpd to the cluster.
      The httpd specialized module: mod_advertise sends UDP message on a multicast group,
      both mod_advertise and the cluster listener joined the multicast group and the cluster receives the messages.
    </para>
    <para>Example for mod_advertise message:</para>
    <programlisting>HTTP/1.0 200 OK
Date: Wed, 08 Apr 2009 12:26:32 GMT
Sequence: 16
Digest: f2d5f806a53effa6c67973d2ddcdd233
Server: 1b60092e-76f3-49fd-9f99-a51c69c89e2d
X-Manager-Address: 127.0.0.1:6666
X-Manager-Url: /bla
X-Manager-Protocol: http
X-Manager-Host: 10.33.144.3</programlisting>
    <para>
      The X-Manager-Address header value is used by the cluster logic to send information about the cluster to the proxy.
      It is the IP and port of the VirtualHost where mod_advertise is configured or URL parameter of the ServerAdvertise directive.
    </para>
    <para>
      See <link linkend="advertise">Proxy Discovery</link> in Configuration Properties and <link linkend="mod_advertise">mod_advertise</link> in Apache httpd configuration.
    </para>
  </section>

  <section>
    <title>What to do if I don't want to use Advertise (multicast):</title>
    <para>In the VirtualHost receiving the MCPM of httpd.conf don't use any Advertise directive or use:</para>
    <programlisting>ServerAdvertise Off</programlisting>
    <para>
      In mod_cluster-jboss-beans.xml add the addresses and ports of the VirtualHost to the proxyList property and set advertise to false, for example:
    </para>
    <programlisting><![CDATA[<property name="proxyList">10.33.144.3:6666,10.33.144.1:6666</property>
<property name="advertise">false</property>]]></programlisting>
    <para>In server.xml (with JBossweb/Tomcat) <programlisting><![CDATA[<Listener className="org.jboss.modcluster.container.catalina.standalone.ModClusterListener" advertise="true"/>]]></programlisting></para>
  </section>

  <section>
    <title>I am using Tomcat 7 / 6 what should I do:</title>
    <para>
      See at the end of <link linkend="java.config">java configuration</link>.
      You can't use the mod_cluster clustered mode with Tomcat so you get a loadbalancing logic similar to mod_jk but with a dynamic configuration.
    </para>
  </section>

  <section>
    <title>It is not working what should I do:</title>
    <para>
      Most likely you have a configuration problem.
      Check the log of the cluster nodes and error_log of httpd.
    </para>

    <section>
      <title>No error</title>
      <para>
        That happens when Advertise is not working: The nodes don't get the <link linkend="advertisemessage">advertise messages</link> from httpd.
      </para>
      <orderedlist>
        <listitem>
          <para>
            Check the modules are loaded and Advertise is started.
            In httpd.conf activate extended information display, add:
          </para>
          <programlisting>AllowDisplay On</programlisting>
          <para>
            When accessing to the <link linkend="SetHandlermod_cluster-manager">mod_cluster_manager</link> you should get something like:
          </para>
          <mediaobject><imageobject role="mod_cluster extended status"><imagedata align="center" fileref="images/mod_status_ext.jpg" format="JPG"/></imageobject></mediaobject>
          <para>
            If not, go to the <link linkend="MinimalExample">Minimal Example</link> and add the missing directive(s).
          </para>
        </listitem>
           
        <listitem>
          <para>
            Check that Advertise message are received on the cluster node.
            A <ulink url="https://github.com/modcluster/mod_cluster/blob/master/test/java/Advertize.java">small Java</ulink> utility could be used to check Advertise.
            It is in the mod_cluster repository and can be compiled using javac.
            A compiled version can be found under in /opt/jboss/httpd/tools in the bundles.
            Run it using java Advertise multicastaddress port.
            The output should be something like:
          </para>
          <programlisting>[jfclere@jfcpc java]$ java Advertize 224.0.1.105 23364
ready waiting...
received: HTTP/1.0 200 OK
Date: Mon, 28 Jun 2010 07:30:31 GMT
Sequence: 1
Digest: df8a4321fa99e5098174634f2fe2f87c
Server: 1403c3be-837a-4e76-85b1-9dfe5ddb4378
X-Manager-Address: test.example.com:6666
X-Manager-Url: /1403c3be-837a-4e76-85b1-9dfe5ddb4378
X-Manager-Protocol: http
X-Manager-Host: test.example.com</programlisting>
        </listitem>

        <listitem>
          <para>No Advertise messages</para>
          <para>
            Check firewall (don't forget the boxes firewall).
            Advertise uses UDP port 23364 and multicast addresse 224.0.1.105
          </para>
        </listitem>
        <listitem>
          <para>Can't get Advertise messages</para>
          <para>
            Use ProxyList property.
            In case Advertise can't work you put the address and port of the VirtualHost used in httpd to receive the MCMP.
            In server/profile/deploy/mod_cluster.sar/META-INF/mod_cluster-jboss-beans.xml
          </para>
          <programlisting><![CDATA[<property name="proxyList">test.example.com:6666</property>]]></programlisting>
          <para>or in server.xml:</para>
          <programlisting><![CDATA[<Listener className="org.jboss.modcluster.container.catalina.standalone.ModClusterListener" proxyList="test.example.com:6666"/>]]></programlisting>
        </listitem>
      </orderedlist>
    </section>

    <section>
      <title>Error in server.log or catalina.out</title>
      <orderedlist>
        <listitem>
          <para>"IO error sending command ":</para>
          <para>
            Check firewall and error_log if there is nothing error_log then it is a firewall problem.
            If you have something like:
          </para>
          <programlisting>18:36:14,533 INFO  [DefaultMCMPHandler] IO error sending command INFO to proxy jfcpc/10.33.144.3:8888</programlisting>
          <para>
            You can use telnet hostname/address port to check by hands that it is OK for example:
          </para>
          <programlisting>[jfclere@jfcpc docs]$ telnet 10.33.144.3 8888
Trying 10.33.144.3...
Connected to jfcpc.
Escape character is '^]'.
GET /
<![CDATA[<html><body><h1>It works!</h1></body></html>]]>Connection closed by foreign host.</programlisting>
          <para>
            Check that the address and port are the expected ones you may use ServerAdvertise On http://hostname:port, like:
          </para>
          <programlisting>ServerAdvertise On http://localhost:6666</programlisting>
          <para>
            Or use the servlet testhttpd in the testhttpd.war of the bundle (in /opt/jboss/httpd/tools).
            Install/deploy it in in the node and start the AS/Tomcat on the node, than access to the node directly and call /testhttpd/testhttpd 
          </para>
          <mediaobject><imageobject role="testhttpd servlet"><imagedata align="center" fileref="images/testhttpd.jpg" format="JPG"/></imageobject></mediaobject>
          <para>
            If you don't get a similar page the output should help to find that is wrong.
          </para>
        </listitem>
      </orderedlist>
    </section>

    <section>
      <title>Error in error_log</title>
      <orderedlist>
        <listitem>
          <para>"client denied by server configuration":</para>
          <para>
            The directory in the VirtualHost is not allowed for the client.
            If you have something like:
          </para>
          <programlisting>Mon Jun 28 18:08:47 2010] [error] [client 10.33.144.3] client denied by server configuration: /</programlisting>
          <para>
            You need to have something like:
          </para>
          <programlisting><![CDATA[<Directory />
  Order deny,allow
  Deny from all
  Allow from 10.33.144.3
</Directory>]]></programlisting>
        </listitem>
      </orderedlist>
    </section>
  </section>

  <section>
    <title>I have "HTTP/1.1 501 Method Not Implemented"</title>
    <para>You need to configure <link linkend="EnableMCPMReceive">EnableMCPMReceive</link> in
      the VirtualHost where you received the MCMP elements in the Apache httpd configuration.
      Something like:
    </para>
    <programlisting><![CDATA[
<VirtualHost localhost:6666>
    <Directory />
     Order deny,allow
     Deny from all
     Allow from 127.0.0.1
    </Directory>
    ServerAdvertise on http://localhost:6666
    EnableMCPMReceive
</VirtualHost>
]]></programlisting>
  </section>

  <section>
    <title>Redirect is not working:</title>
    <para>
      When using http/https instead AJP proxyname, proxyhost and redirect must be configured in the Connector.
      Something like:
      <programlisting><![CDATA[    <Connector port="8080" protocol="HTTP/1.1" 
               connectionTimeout="20000"
               proxyName="httpd_host_name"
               proxyPort="8000"
               redirectPort="443" />]]></programlisting>
    </para>
  </section>

  <section>
    <title>I have more than one Connector mod_cluster does use the right one</title>
    <para>
      Mod_cluster tries to use the first AJP connector configured. If there isn't any AJP connector
      it uses the http or https that has the biggest maxthreads value. That is "maxThreads" in Tomcat and JBossAS4/5/6:
      <programlisting><![CDATA[    <Connector port="8080" protocol="HTTP/1.1" maxThreads="201" />]]></programlisting>
      Or "max-connections" in AS7: (32 * processor + 1 for native and 512 * processor + 1 for JIO).
      <programlisting><![CDATA[    <connector name="http" protocol="HTTP/1.1" scheme="http" socket-binding="http" max-connections="513" />]]></programlisting>
    </para>
  </section>
  <section>
    <title>Chrome can't diplay /mod_cluster_manager page</title>
    <para>
      When using chrome with mod_cluster_manager the page is not displayed and the following error is displayed:
      <programlisting><![CDATA[ Error 312 (net::ERR_UNSAFE_PORT): Unknown error. ]]></programlisting>
      you can change the port of the VirtualHost to 7777 or any value chrome accepts or
      add:
      <programlisting><![CDATA[ --explicitly-allowed-ports=6666 ]]></programlisting> to the start parameters of chrome.
    </para>

  </section>

  <section>
    <title>Using mod_cluster and SELinux.</title>
    <para>
     Mod_cluster needs to open port and create shared memory and files, therefore some permissions
     have to be added, you need to configure something like:
<programlisting><![CDATA[
policy_module(mod_cluster, 1.0)

require {
        type unconfined_java_t;
        type httpd_log_t;
        type httpd_t;
        type http_port_t;
        class udp_socket node_bind;
        class file write;
}

#============= httpd_t ==============

allow httpd_t httpd_log_t:file write;
corenet_tcp_bind_generic_port(httpd_t)
corenet_tcp_bind_soundd_port(httpd_t)
corenet_udp_bind_generic_port(httpd_t)
corenet_udp_bind_http_port(httpd_t)

#============= unconfined_java_t ==============
allow unconfined_java_t http_port_t:udp_socket node_bind;
]]></programlisting>
     Put the above in a file for example mod_cluster.te and generate the mod_cluster.pp file (for example in Fedora 16):
<programlisting><![CDATA[
[jfclere@jfcpc docs]$ make -f /usr/share/selinux/devel/Makefile
Compiling targeted mod_cluster module
/usr/bin/checkmodule:  loading policy configuration from tmp/mod_cluster.tmp
/usr/bin/checkmodule:  policy configuration loaded
/usr/bin/checkmodule:  writing binary representation (version 14) to tmp/mod_cluster.mod
Creating targeted mod_cluster.pp policy package
rm tmp/mod_cluster.mod.fc tmp/mod_cluster.mod
]]></programlisting>
     The mod_cluster.pp file should be proceeded by semodule as root:
<programlisting><![CDATA[
root@jfcpc docs]# semodule -i mod_cluster.pp
[root@jfcpc docs]# 
]]></programlisting>
    </para>
  </section>
  <section id="systemproperties">
    <title>System properties to modify behaviour</title>
    <para>org.jboss.modcluster.container.catalina.status-frequency (default: 1) send STATUS
          messages only 1/n periodic event (tomcat, jbossweb).
          The events occur every backgroundProcessorDelay (default 10 seconds).
    </para>
  </section>

</chapter>
