<?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="Quick_Start_Guide">
  <title>Quick Start Guide</title>

  <para>The following are the steps to set up a minimal working installation
  of mod_cluster on a single httpd server and a single back end server, either
  JBoss AS, JBossWeb or Tomcat. The steps can be repeated to add as many httpd
  servers or back end servers to your cluster as is desired.</para>

  <para>The steps shown here are not intended to demonstrate how to set up a
  production install of mod_cluster; for example <link linkend="UsingSSL">
  using SSL to secure access</link> to the httpd-side mod_manager component is not covered.
  See the <link linkend="nativeconfig">httpd-side</link> and
  <link linkend="javaconf">java-side</link>
  configuration documentation for the full set of configuration
  options.</para>

  <sect2>
    <title>Download mod_cluster components</title>

    <para>Download the latest <ulink
    url="http://www.jboss.org/mod_cluster/downloads/latest.html">httpd
    and java release bundles</ulink>. If there is no pre-built httpd bundle
    appropriate for your OS or system architecture, you can <link
    linkend="building">build the
    binary from source</link>.</para>
  </sect2>

  <sect2>
    <title>Install the httpd binary</title>

    <sect3>
      <title>Install the whole httpd</title>

      <para>The httpd-side bundles are gzipped tars and include a full httpd
      install. As they contain already an Apache httpd install you don't need
      to download Apache httpd. Just extract them in root,
      e.g.<programlisting>
  cd /
  tar xvf mod-cluster-1.0.0-linux2-x86-ssl.tar.gz</programlisting></para>

      <para>That will give you a full httpd install in your /opt/jboss
      directory.</para>
    </sect3>

    <sect3>
      <title>Install only the modules</title>

      <para>If you already have a working httpd install that you would prefer
      to use, you'll need to download the bundle named mod_cluster httpd
      dynamic libraries corresponding to you plaform, extract the modules and
      copy them directory to your httpd install's module directory.</para>

      <programlisting>
  cd /tmp
  tar xvf mod_cluster-1.0.0.CR2-linux2-x86-so.tar.gz </programlisting>

      <para>And then you have to copy the files below to you module
      directory:</para>

      <para> * mod_proxy.so</para>

      <para> * mod_proxy_ajp.so</para>

      <para> * mod_slotmem.so</para>

      <para> * mod_manager.so</para>

      <para> * mod_proxy_cluster.so</para>

      <para> * mod_advertise.so</para>
    </sect3>

    <sect3>
      <title>Install in home directory</title>

      <para>Since 1.1.0.CR2 a script opt/jboss/httpd/sbin/installhome.sh
      allows reconfiguration of the bundle installation so that it can run in
      user's home directory. To do that just extract the bundle in your home
      directory and run the script. Once that done, httpd will run on port
      8000 and will accept MCMP messages on localhost:6666 and offer
      /mod_cluster_manager on the same host and port.</para>
    </sect3>

    <sect3>
      <title>Install in windows</title>

      <para>To install in windows unzip the bundle corresponding to your
      architecture. You may run httpd directly by using:</para>

      <programlisting>
  httpd-2.2\bin\httpd.exe -k start </programlisting>

      <para>or install Apache httpd as a service:</para>

      <programlisting>
  httpd-2.2\bin\httpd.exe -k install </programlisting>

      <para>and start the service:</para>

      <programlisting>
  net start Apache2.2 </programlisting>

      <para>Note that in the windows bundles have a flat directory structure,
      so you have <emphasis>httpd-2.2/modules/</emphasis> instead of
      <emphasis>opt/jboss/httpd/lib/httpd/modules.</emphasis></para>
    </sect3>
  </sect2>

  <sect2>
    <title>Configure httpd</title>

    <para>Since 1.1.0.CR2 httpd.conf is preconfigured with the Quick Start
    values. You should adapt the default values to your configuration with
    older mod_cluster we will have to add the following to httpd.conf. If you
    extracted the download bundle to root as shown above and are using that
    extract as your httpd install, httpd.conf is located in
    /opt/jboss/httpd/httpd/conf.<programlisting> LoadModule proxy_module /opt/jboss/httpd/lib/httpd/modules/mod_proxy.so
 LoadModule proxy_ajp_module /opt/jboss/httpd/lib/httpd/modules/mod_proxy_ajp.so
 LoadModule slotmem_module /opt/jboss/httpd/lib/httpd/modules/mod_slotmem.so
 LoadModule manager_module /opt/jboss/httpd/lib/httpd/modules/mod_manager.so
 LoadModule proxy_cluster_module /opt/jboss/httpd/lib/httpd/modules/mod_proxy_cluster.so
 LoadModule advertise_module /opt/jboss/httpd/lib/httpd/modules/mod_advertise.so
 
 Listen 10.33.144.3:6666
 &lt;VirtualHost 10.33.144.3:6666&gt;
 
   &lt;Directory /&gt;
      Order deny,allow
      Deny from all
      Allow from 10.33.144.
   &lt;/Directory&gt;
 
 KeepAliveTimeout 60
 MaxKeepAliveRequests 0
 
 ManagerBalancerName mycluster
 AdvertiseFrequency 5
 
 &lt;/VirtualHost&gt;</programlisting></para>

    <para>If you are using your own install of httpd, httpd.conf is found in
    your install's conf directory. The content to add to httpd.conf is
    slightly different from the above (different path to the various .so
    files):<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;Directory /&gt;
      Order deny,allow
      Deny from all
      Allow from 10.33.144.
   &lt;/Directory&gt;
 
 KeepAliveTimeout 60
 MaxKeepAliveRequests 0
 
 ManagerBalancerName mycluster
 AdvertiseFrequency 5
 
 &lt;/VirtualHost&gt;</programlisting></para>
  </sect2>

  <sect2>
    <title>Install the Java-side binaries</title>

    <para>First, extract the java-side binary to a temporary directory. The
    following assumes it was extracted to /tmp/mod-cluster</para>

    <para>Your next step depends on whether your target server is JBoss AS or
    JBossWeb/Tomcat.</para>

    <sect3>
      <title>Installing in JBoss AS 6.0.0.M1 and up</title>

      <para>You don't need to do anything to install the java-side binaries in
      AS 6.x; it's part of the AS distribution's default, standard and all
      configurations.</para>
    </sect3>

    <sect3>
      <title>Installing in JBoss AS 5.x</title>

      <para>Assuming $JBOSS_HOME indicates the root of your JBoss AS install
      and that you want to use mod_cluster in the AS's all config:</para>
<programlisting>
  cp -r /tmp/mod-cluster/mod-cluster.sar $JBOSS_HOME/server/all/deploy
</programlisting>
    </sect3>

    <sect3>
      <title>Installing in JBoss Web or Tomcat</title>

      <para>Assuming $CATALINA_HOME indicates the root of your JBossWeb or
      Tomcat install:</para>

      <programlisting>cp -r /tmp/mod-cluster/JBossWeb-Tomcat/lib/*
      $CATALINA_HOME/lib/ </programlisting>
    </sect3>

    <sect3>
      <title>Installing in JBoss AS 4.2.x or 4.3.x</title>

      <para>Assuming $JBOSS_HOME indicates the root of your JBoss AS install
      and that you want to use mod_cluster in the AS's all config:</para>

      <programlisting>
      cp -r /tmp/mod-cluster/JBossWeb-Tomcat/lib/mod-cluster.jar $JBOSS_HOME/server/all/deploy/jboss-web.deployer </programlisting>
    </sect3>
  </sect2>

  <sect2>
    <title>Configuring JBoss AS, JBoss Web or Tomcat</title>

    <para>mod_cluster is integrated into your web server by adding an
    implementation of the Tomcat LifecycleListener interface to the server's
    configuration, and by giving each node a unique name.</para>

    <sect3>
      <title>Integrate mod_cluster with JBoss AS's embedded JBossWeb</title>

      <para>Edit the $JBOSS_HOME/server/all/deploy/jbossweb.sar/server.xml
        file, adding the following next to the other Listener elements:</para>

      <programlisting>
      &lt;Listener
      className="org.jboss.web.tomcat.service.deployers.MicrocontainerIntegrationLifecycleListener"
                 delegateBeanName="ModClusterService"/&gt; </programlisting>

      <para>Edit the $JBOSS_HOME/server/all/deploy/jbossweb.sar/META-INF/jboss-beans.xml
        file, adding the following next to the other depends elements:</para>

      <programlisting>
      &lt;depends&gt;ModClusterService&lt;/depends&gt; </programlisting>
      
    </sect3>

    <sect3>
      <title>Integrate mod_cluster with standalone JBossWeb or Tomcat</title>

      <para>Edit the $CATALINA_HOME/conf/server.xml file, adding the following
      next to the other Listener elements:</para>

      <programlisting>
      &lt;Listener
      className="org.jboss.modcluster.ModClusterListener"
                 advertise="true"/&gt; </programlisting>
    </sect3>

    <sect3>
      <title>Integrate mod_cluster with JBoss AS 4.2.x and 4.3.x</title>

      <para>Edit the
      $JBOSS_HOME/server/all/deploy/jboss-web.deployer/server.xml file, adding
      the following next to the other Listener elements:</para>

      <programlisting>
      &lt;Listener
      className="org.jboss.modcluster.ModClusterListener"
                 advertise="true"/&gt; </programlisting>

      <para />
    </sect3>

    <sect3>
      <title>Configure a jvmRoute</title>

      <para>Each back end server in your cluster needs to have a unique name,
      known as a "jvmRoute". This is configured by adding an attribute to the
      Engine element in server.xml.</para>

      <programlisting>
      &lt;Engine name="jboss.web" defaultHost="localhost"
      jvmRoute="node01"&gt; </programlisting>

      <para>If your cluster includes multiple back-end servers, you must
      assign a different jvmRoute to each server.</para>

      <para>Beginning with the 1.1.0.BETA1 release, configuring a jvmRoute is
      no longer absolutely required; if one isn't provided mod_cluster will
      generate one from the address and port of the Connector used for
      receiving requests, plus the name of the Tomcat Engine. Still,
      configuring a jvmRoute is recommended, since the jvmRoute is appended to
      all session ids. The generated jvmRoute is lengthy and includes
      information you may not want to expose to the internet via session
      ids.</para>
    </sect3>
  </sect2>

  <sect2>
    <title>Start httpd</title>

    <para>To start httpd do the following:</para>

    <programlisting>
    /opt/jboss/httpd/sbin/apachectl start </programlisting>
  </sect2>

  <sect2>
    <title>Start the back end server</title>

    <sect3>
      <title>Starting JBoss AS</title>

      <programlisting>
      cd $JBOSS_HOME/bin ./run.sh -c all </programlisting>
    </sect3>

    <sect3>
      <title>Starting JBossWeb or Tomcat</title>

      <programlisting>
      cd $CATALINA_HOME ./startup.sh </programlisting>
    </sect3>
  </sect2>

  <sect2>
    <title>Set up more back end servers</title>

    <para>Repeat the back end server install and configuration steps; just be
    sure to use a different jvmRoute for each server.</para>
  </sect2>

  <sect2>
    <title>Experiment with the Load Balancing Demo Application</title>

    <para>The <link linkend="demo">load
    balancing demo application</link> is a good way to learn about
    mod_cluster's capabilities.</para>

    <para />
  </sect2>
</chapter>
