<?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" [
]>
<chapter>
    <title>Installation</title>

    <section>
        <title>Download</title>
        <para>
            JGroups can be downloaded <ulink url="http://sourceforge.net/projects/javagroups/files/JGroups/">here</ulink>.
            For this tutorial, I&apos;m using the binary version of JGroups 3.0, so download one of the jgroups-3.x.y.jar
            files (e.g. jgroups-3.0.0.Final.jar).
        </para>

        <para>
            This JAR file contains:
            <itemizedlist>
                <listitem>
                    <para>JGroups core, demo and (selected) test classes</para>
                </listitem>
                <listitem>
                    <para>INSTALL.html: detailed configuration instructions plus trouble shooting</para>
                </listitem>
                <listitem>
                    <para>Sample configuration files, e.g. udp.xml or tcp.xml</para>
                </listitem>
            </itemizedlist>
        </para>

        <note>
            <para>Note that JGroups 3.0 requires JDK 6.</para>
        </note>
    </section>


    <section>
        <title>Configuration</title>
        <para>
            Add jgroups-3.x.y.jar to your classpath. If you use the log4j logging system, you also
            have to add log4j.jar (this is not necessary if you use the JDK logging system).
        </para>
    </section>

    <section>
        <title>Testing your Setup</title>

        <para>To see whether your system can find the JGroups classes, execute the following command:</para>

        <screen>java org.jgroups.Version</screen>

        <para>or</para>

        <screen>java -jar jgroups-3.x.y.jar</screen>

        <para>You should see the following output (more or less) if the
            class is found:</para>

        <screen>
$  java org.jgroups.Version
   Version:      3.0.0.Beta1</screen>

    </section>

    <section>
        <title>Running a Demo Program</title>

        <para>
            To test whether JGroups works okay on your machine, run the following command twice:
        </para>

        <screen>java -Djava.net.preferIPv4Stack=true org.jgroups.demos.Draw</screen>

        <para>
            Two whiteboard windows should appear as shown below:
        </para>

        <figure id="DrawScreenshotFig">
            <title>Screenshot of 2 Draw instances</title>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="images/DrawScreenshot.png"
                               format="PNG"
                               align="center" />
                </imageobject>
            </mediaobject>
        </figure>

        <para>
            If you started them simultaneously, they could initially show a membership of 1 in
            their title bars. After some time, both windows should show 2. This means that the two instances found
            each other and formed a cluster.
        </para>

        <para>
            When drawing in one window, the second instance should also be updated. As the default group transport
            uses IP multicast, make sure that - if you want start the 2 instances in different subnets
            - IP multicast is enabled. If this is not the case, the 2 instances won&apos;t &apos;find&apos; each other and the
            example won&apos;t work.
        </para>

        <para>
            If the 2 instances find each other and form a cluster, you can skip ahead to the next chapter ("Writing
            a simple application").
        </para>

    </section>

    <section>
        <title>Using JGroups without a network</title>

        <para>
            (You may skip this section if the 2 instances found each other correctly in the previous section).
        </para>

        <para>Sometimes there isn&apos;t a network connection (e.g. DSL modem is down), or we want to multicast only on the
            local machine. To do this, we can use the loopback device (127.0.0.1):
        </para>
        <screen>java -Djgroups.bind_addr=127.0.0.1 -Djava.net.preferIPv4Stack=true org.jgroups.demos.Draw</screen>

        <para>
            You should again see 2 instances of Draw which form a cluster. If this is not the case, you may
            have to add a multicast route to the loopback device (this requires superuser or admin privileges):
        </para>

        <screen>route add -net 224.0.0.0 netmask 240.0.0.0 dev lo</screen>

        <para>This means that all traffic directed to the 224.0.0.0 network will be sent to the loopback interface,
            which means it doesn&apos;t need any network to be running.
        </para>

        <para>Typical home networks have a gateway/firewall with 2 NICs: the first (eth0) is connected to the outside
            world (Internet Service Provider), the second (eth1) to the internal network, with the gateway
            firewalling/masquerading traffic between the internal and external networks. If no route for multicast
            traffic is added, the default will be to use the default gateway, which will typically direct the
            multicast traffic towards the ISP. To prevent this (e.g. ISP drops multicast traffic, or latency is too
            high), we recommend to add a route for multicast traffic which goes to the internal network (e.g. eth1).
        </para>

    </section>

    <section>
        <title>Trouble shooting</title>
        <para>
            If the 2 Draw instances don&apos;t find each other, read INSTALL.html, which comes with JGroups and has more
            detailed trouble shooting information. In a nutshell, there are multiple possible reasons the cluster
            doesn&apos;t form:
            <itemizedlist>
                <listitem>
                    <para>
                        A firewall discards packets. To verify this, turn the firewall off. If the cluster forms, then turn
                        the firewall back on and selectively add rules to let JGroups traffic pass.
                    </para>
                </listitem>
                <listitem>
                    <para>
                    Use of IPv6. JGroups does work with IPv6, but some JDK implementations still have issues with it, so
                    you can turn IPv6 off by passing the "-Djava.net.preferIPv4Stack=true" system property to the JVM.
                    You can force use of IPv6 addresses by using setting system property
                    -Djava.net.preferIPv6Addresses=true. If you use IPv6 addresses, you should also define IPv6 addresses
                    in your configuration; e.g. if you set bind_addr="192.168.1.5" in UDP, JGroups will try to pick
                    IPv4 addresses if an IPv4 stack is available, or you&apos;re running a dual stack.
                    </para>
                </listitem>
                <listitem>
                    <para>
                    You don&apos;t use the right network interface (NIC): define the NIC with the -Djgroups.bind_addr system
                    property:</para>
                    <screen>java -Djgroups.bind_addr=192.168.5.2 java.org.jgroups.demos.Draw</screen>
                </listitem>
                <listitem>
                    <para>There is no multicast route for the chosen NIC.</para>
                </listitem>
            </itemizedlist>
        </para>
    </section>


</chapter>



