<chapter>
    <title>Installation and Configuration</title>

    <para>The installation refers to version 3.x of JGroups. Refer to the installation
        instructions (INSTALL.html) that are shipped with the JGroups version you downloaded for details.
    </para>

    <para>
        The JGroups JAR can be downloaded from <ulink url="http://sourceforge.net/projects/javagroups/files/JGroups/">
        SourceForge</ulink>. It is named jgroups-x.y.z, where x=major, y=minor and z=patch version, for example
        jgroups-3.0.0.Final.jar.
        The JAR is all that's needed to get started using JGroups; it contains all core, demo and (selected) test
        classes, the sample XML configuration files and the schema.
    </para>

    <para>
        The source code is hosted on <ulink url="https://github.com/belaban/jgroups">GitHub</ulink>. To build JGroups,
        ANT is currently used. In <xref linkend="BuildingJGroups"/> we'll show how to build JGroups from source.
    </para>

    <section id="Requirements">
        <title>Requirements</title>

        <itemizedlist>
            <listitem>
                JGroups 3.x requires JDK 6 or higher.
            </listitem>
            <listitem>
                There is no JNI code present so JGroups should run on all platforms.
            </listitem>
            <listitem>
                If you want to generate HTML-based test reports from the
                unittests, then xalan.jar needs to be in the CLASSPATH (also
                available in the lib directory)
            </listitem>
        </itemizedlist>

    </section>


    <section id="SourceStructure">
        <title>Structure of the source version</title>

        <para>The source version consists of the following directories and files:</para>

        <itemizedlist>
            <listitem>
                <para>src: the sources</para>
            </listitem>
            <listitem>
                <para>tests: unit and stress tests</para>
            </listitem>
            <listitem>
                <para>lib: JARs needed to either run the unit tests, or build the manual etc. No JARs from here are
                    required at runtime !
                </para>
            </listitem>
            <listitem>
                <para>conf: configuration files needed by JGroups, plus default protocol stack definitions</para>
            </listitem>
            <listitem>
                <para>doc: documentation</para>
            </listitem>
        </itemizedlist>

    </section>

    <section id="BuildingJGroups">
        <title>Building JGroups (source distribution only)</title>

        <orderedlist>
            <listitem>
                <para>
                    Download the sources from <ulink url="https://github.com/belaban/jgroups">GitHub</ulink>, either
                    via 'git clone', or the
                    <ulink url="https://github.com/belaban/JGroups/archives/master">download link</ulink> into
                    a directory "JGroups", e.g. /home/bela/JGroups.
                </para>
            </listitem>
            <listitem>
                <para>Change to the JGroups directory</para>
            </listitem>
            <listitem>
                <para>On UNIX systems use <filename>build.sh</filename>, on Windows
                    <filename>build.bat</filename>:
                    <userinput>$&gt;
                        ./build.sh</userinput>
                </para>
            </listitem>
            <listitem>
                <para>This will compile all Java files (into the <filename>classes</filename> directory).
                </para>
            </listitem>
            <listitem>
                <para>To generate the JARs:
                    <userinput>$&gt; ./build.sh jar</userinput>
                </para>
            </listitem>
            <listitem>
                <para>This will generate the following JAR files in the
                    <filename>dist</filename>  directory:
                </para>
                <itemizedlist>
                    <listitem>
                        <para>
                            <filename>jgroups-3.x.y.jar</filename>
                            - the JGroups JAR
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            <filename>jgroups-sources.jar</filename>
                            - the source code for the core classes and demos.
                        </para>
                    </listitem>
                </itemizedlist>
            </listitem>
            <listitem>
                <para>
                    Now add the following directories to the classpath:
                </para>
                <orderedlist>
                    <listitem>
                        <para>
                            <filename>JGroups/classes</filename>
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            <filename>JGroups/conf</filename>
                        </para>
                    </listitem>
                    <listitem>
                        <para>All needed JAR files in
                            <filename>JGroups/lib</filename>
                            . To build from sources, the two
                            Ant JARs are required. To run unit tests, the JUnit (and
                            possibly Xalan) JARs are needed.
                        </para>
                    </listitem>
                </orderedlist>
            </listitem>
            <listitem>
                <para>To generate JavaDocs simple run
                    <userinput>$&gt;
                        ./build.sh javadoc</userinput>
                    and the Javadoc documentation will be generated in the <filename>dist/javadoc</filename>
                    directory
                </para>
            </listitem>
            <listitem>
                <para>Note that - if you already have Ant installed on your
                    system - you do not need to use build.sh or build.bat, simply
                    invoke ant on the build.xml file. To be able to invoked ant
                    from any directory below the root directory, place
                    <userinput>ANT_ARGS="-find build.xml -emacs"</userinput>
                    into
                    the
                    <filename>.antrc</filename>
                    file in your home
                    directory.
                </para>
            </listitem>
            <listitem>
                <para>For more details on Ant see
                    <ulink url="http://jakarta.apache.org/ant/"/>.
                </para>
            </listitem>
        </orderedlist>
    </section>

    <section id="TestingTheSetup">
        <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-all.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 id="RunningTheDemo">
        <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>2 whiteboard windows should appear as shown in <xref linkend="DrawScreenshotFig"/>.

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

            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't 'find' each other and the
            example won't work.
        </para>

         <para>You can change the properties of the demo to for example use
            a different transport if multicast doesn't work (it should always
            work on the same machine). Please consult the documentation to see how to do this.
         </para>

        <para>
            State transfer (see the section in the API later) can also be tested by passing the -state flag to Draw.
        </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 IP Multicasting without a network connection</title>

        <para>Sometimes there isn't a network connection (e.g. DSL modem
            is down), or we want to multicast only on the local machine. For
            this the loopback interface (typically lo) can be configured,
            e.g.</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't need any network to be running. Note that the 224.0.0.0
            network is a placeholder for all multicast addresses in most UNIX
            implementations: it will catch
            <emphasis>all</emphasis> multicast
            traffic. This is an undocumented feature of
            <filename>/sbin/route</filename>
            and may not work across all UNIX
            flavors. The above instructions may also work for Windows systems,
            but this hasn't been tested. Note that not all systems allow
            multicast traffic to use the loopback interface.
        </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 fdefault 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 id="ItDoesntWork">
        <title>It doesn't work !</title>

        <para>Make sure your machine is set up correctly for IP
            multicast. There are 2 test programs that can be used to detect
            this: McastReceiverTest and McastSenderTest. Start
            McastReceiverTest, e.g.</para>

        <screen>java org.jgroups.tests.McastReceiverTest</screen>

        <para>Then start McastSenderTest:</para>

        <screen>java org.jgroups.tests.McastSenderTest</screen>

        <para>If you want to bind to a specific network interface card (NIC), use -bind_addr 192.168.0.2,
        where 192.168.0.2 is the IP address of the NIC to which you want to bind. Use this parameter in both
        sender and receiver.</para>

        <para>You should be able to type in the McastSenderTest window and
            see the output in the McastReceiverTest. If not, try to use -ttl
            32 in the sender. If this still fails, consult a system
            administrator to help you setup IP multicast correctly. If you are
            the system administrator, look for another job :-)</para>

        <para>Other means of getting help: there is a public forum on
            <ulink url="http://jira.jboss.com/jira/browse/JGRP">JIRA</ulink>
            for questions. Also consider subscribing to the javagroups-users
            mailing list to discuss such and other problems.
        </para>

    </section>

    <section id="IPv6Issues">
        <title>Problems with IPv6</title>

        <para>Another source of problems might be the use of IPv6, and/or misconfiguration of
            <filename>/etc/hosts</filename>. If you
            communicate between an IPv4 and an IPv6 host, and they are not
            able to find each other, try the
            <parameter>-Djava.net.preferIP4Stack=true</parameter>
            property,
            e.g.
        </para>

        <screen>java -Djava.net.preferIPv4Stack=true org.jgroups.demos.Draw -props /home/bela/udp.xml</screen>

        <para>The JDK uses IPv6 by default, although is has a dual stack, that is, it also supports IPv4.
            <ulink url="http://java.sun.com/j2se/1.4/docs/guide/net/ipv6_guide/">Here's</ulink>
            more details on the subject.
        </para>

    </section>

    <section>
        <title>Wiki</title>
        <para>
            There is a wiki which lists FAQs and their solutions at
            <ulink url="http://www.jboss.org/wiki/Wiki.jsp?page=JGroups"/>. It is frequently updated and a useful companion
            to this user's guide.
        </para>
    </section>

    <section>
        <title>I have discovered a bug !</title>

        <para>If you think that you discovered a bug, submit a bug report
            on
            <ulink url="http://jira.jboss.com/jira/browse/JGRP">JIRA</ulink>
            or send email to the jgroups-users mailing list if you're unsure about it. Please
            include the following information:
        </para>

        <itemizedlist>
            <listitem>
                <para>Version of JGroups (java org.jgroups.Version)</para>
            </listitem>
            <listitem>
                <para>Platform (e.g. Solaris 8)</para>
            </listitem>
            <listitem>
                <para>Version of JDK (e.g. JDK 1.4.2_07)</para>
            </listitem>
            <listitem>
                <para>Stack trace. Use kill -3 PID on UNIX systems or
                    CTRL-BREAK on windows machines</para>
            </listitem>
            <listitem>
                <para>Small program that reproduces the bug</para>
            </listitem>
        </itemizedlist>

    </section>
    <section id="SupportedClasses">
        <title>Supported classes</title>
        <para>
            JGroups project has been around since 1998. Over this time, some of the JGroups classes
            have been used in experimental phases and have never been matured enough to be used in today's production
            releases. However, they were not removed since some people used them in their products.
    </para>
    
    <para>
        The following tables list unsupported and experimental classes. These classes are not actively maintained, and
        we will not work to resolve potential issues you might find. Their final faith is not yet determined; they
        might even be removed altogether in the next major release. Weight your risks if you decide to use them anyway.
    </para>
        <section id="ExperimentalClasses">
            <title>Experimental</title>          
            ${Experimental}
        </section>
        <section id="UnsupportedClasses">
            <title>Unsupported</title>          
            ${Unsupported}
        </section>
    </section>       
</chapter>
