------------------------------------------------------------------------- Jgroup/ARM Release Notes and Installation Instructions ------------------------------------------------------------------------- 1. INTRODUCTION The aim of this document is to explain how to install the Jgroup/ARM dependable computing toolkit, and start the example applications included with the Jgroup/ARM distribution. In this document, we assume a basic knowledge of the main characteristics of Jgroup/ARM. Please refer to the Jgroup/ARM tutorial and programmers manual available at the project site for a more exhaustive description of Jgroup/ARM and its functionality. The project's web site: http://www.cs.unibo.it/projects/jgroup/ 2. OVERVIEW OF MAJOR CHANGES SINCE JGROUP VERSION 1.1 Complete rewrite of the low level multicast layer. It now uses IP multicast within each LAN environment, and unicast between LANs to a leader node who will perform a multicast within its local LAN. A substantial amount of effort has gone into avoiding unnecessary object creation and memory copying, especially at the lower layers. Added an XML based system configuration framework. It allows you to specify applications, services (layers) and the machines included in your distributed system. Reflection based layer composition framework, allowing easily configurable layer compositions. The Autonomous Replication Management framework is now also bundled with Jgroup (residing in the jgroup.arm package). This framework feature seamless replica distribution, and a recovery mechanism to ensure that the redundancy level requirements are maintained for each application. 3. SOFTWARE REQUIREMENTS This version of Jgroup/ARM requires - Java J2SE version 1.3 or newer http://java.sun.com/ - Apache Ant version 1.4 or newer http://jakarta.apache.org/ant/ - Some Java XML parser library (e.g., Crimson) http://xml.apache.org/crimson/ (included in distribution: crimson.jar and jaxp.jar) - Apache Log4j version 1.2.4 or newer http://jakarta.apache.org/log4j/ (included in distribution: log4j-1.2.5.jar) Note that Jgroup/ARM is currently being developed using Java J2SE version 1.4. The Ant package is an open-source, cross-platform, Java-based build tool developed by the Apache Software Foundation. Ant build files are written in XML, and may be easily manipulated using standard editors or by XML tools. We use Ant to provide a cross-platform, easy to use and install version of Jgroup/ARM. Note however, that Jgroup/ARM can be used also without the Ant package. This requires that you use alternative means for compiling and running your applications based on Jgroup/ARM. Jgroup/ARM depends on a number of XML based configuration files that is used to describe the distributed system, application-specific properties and Jgroup service interrelations. Alternative implementations of Java XML parsers may also work with Jgroup/ARM, but this has yet to be tested. The Log4j logging package is used by Jgroup/ARM, primarily for debugging purposes. Actually, most debug code can be disabled entirely as explained later. 3.1. OPTIONAL SOFTWARE Some parts of Jgroup/ARM extend Jini, and thus will need the following - Jini version 1.1 (newer versions not tested) http://www.jini.org/ (included in distribution: jini-core.jar, mahalo.jar, reggie.jar) 4. INSTALLATION PROCEDURE AND DISTRIBUTION CONTENT Note, that these instructions assume that the Ant build tool is available on your system. Simply unzip the Jgroup/ARM distribution archive somewhere on your file system. This will create a directory, tagged with the build date for Jgroup/ARM. The content of the distribution is summarized below: - src/ Contains the source files for Jgroup/ARM, excluding Jini related source code. - doc/ Contains the Javadoc-generated documentation for Jgroup/ARM. - lib/ Contains the jar files needed by Jgroup/ARM to run, including the jaxp.jar and crimson.jar libraries needed to parse XML files, the log4j libraries, and jini related libraries. And of course the jgroup.jar that contains the Jgroup/ARM runtime environment and the example applications. - config/ Contains the configuration files required by Jgroup/ARM to function correctly. The configuration files are quite intuitive, but only the config.xml file needs to be modified to run the examples described below. Please refer to the Jgroup/ARM tutorial for details on how to edit the various configuration files. - build.xml The XML file needed by Ant to build Jgroup/ARM, and also to run the various applications provided with the distribution. - license.txt The Anthill license (GNU Lesser Public General License) - readme.txt A brief description of Jgroup/ARM, and some of the changes since the previous release of Jgroup. 4.1 PROJECT HELP Assuming that Ant is installed on your system, you may wish to examine the available build and run targets included in the Jgroup/ARM build file. To do this, simply execute the following command: ant -projecthelp 4.2 COMPILING FROM SOURCE This step can be skipped if you just wish to test the various example applications provided with Jgroup/ARM. To compile Jgroup/ARM from source, you can simply type: ant If you wish to recompile everything, type: ant all IMPORTANT: To ensure that the compiled software is the one being used when running, you need to edit the build.xml file so that the run property points to the classes/ directory instead of the jgroup.jar. 4.3 SYSTEM CONFIGURATION To be able to use Jgroup/ARM, you must ensure to add all hosts that you wish to run Jgroup/ARM applications on, are in the configuration file (config/config.xml). The config/sample-config.xml illustrates the overall structure of the config.xml file. You may wish to make a copy of the sample-config.xml file, naming it config.xml, and edit this file. Each host must be within a domain, and this corresponds to the DNS domain of your hosts. Each domain may specify a multicast address and port that will be used by the Jgroup/ARM runtime system for communication within that domain (LAN). Also each host may specify the port on which it will communicate unicast messages. If you do not specify the various ports and the multicast address, defaults will be obtained from the config.dtd file. 5. TESTING THE PROVIDED JGROUP EXAMPLE APPLICATIONS The Jgroup distribution contains a small number of simple applications, whose aim provide an example of use of the Jgroup programming model. 5.1. RUNNING THE DEPENDABLE REGISTRY Most applications included in the Jgroup/ARM distribution requires a registry service. For this purpose Jgroup provides a dependable version of the Java RMI registry, composed of a group of registry replicas capable of maintaining associations between object group names and object group composition. In order to run a registry replica, the following command has to be executed: ant dregistry Each registry replica instance will look for other instances of the registry in its distributed system by probing each of the hosts specified in the config.xml file, and forms a group with them. 5.2. THE MANDATORY HELLO WORLD APPLICATION Also Jgroup contains a classical HelloWorld application composed of an hello client that performs an anycast group method invocation of method sayHello on a group of hello servers. Method sayHello returns a greeting and a set of time values obtained through an internal invocation. In order to run the application, the first step is to execute a set of dependable registry replicas, using the command as described in Section 5.1. Each instance of the dependable registry should be started on a separate machine to make it dependable to machine crashes. The second step is to run a set of hello servers by executing the following command (also this on several different machines): ant helloserver Finally, an instance of the hello client application may be run by executing the following command: ant helloclient 5.3. GMI PERFORMANCE EVALUATION Jgroup contains a speed test application to evaluate the performance of external group method invocations. The performance test is composed of a speed server and a speed client. In order to run the test, the first step is to run a set of dependable registry replicas neeeded by the clients to locate the servers. The second step is to run a set of speed servers, depending on the configuration you want to test. Finally, a set of speed clients is executed. To run a GMI speed server, the following command should be used: ant speedserver In order to run a GMI speed client, use the following command: ant speedclient 5.4. RMI PERFORMANCE EVALUATION The test package contains also a simple test to evaluate the performance of standard RMI, which is useful for comparing standard RMI with GMI. This applications executes the same tests as those performed by the application in Section 5.3, but using RMI instead of GMI. To run the RMI speed server, use the following command: ant rmispeedserver In order to run a RMI speed client, use the following command: ant rmispeedclient 5.5. THE MULTICAST EXAMPLE Mcast is a simple example that shows how Jgroup can be used as a traditional message based group communication service. To run a mcast server, issue the following command: ant mcast 6. TESTING THE PROVIDED ARM EXAMPLE APPLICATIONS The Autonomous Replication Management (ARM) framework enables you to start applications on a set of machines specified in your config.xml file. To enable this feature of Jgroup/ARM, each of your hosts must be running the execution daemon, and there must also be at least on replication manager within the system. Note that the ARM framework is still work-in-progress. 6.1. STARTING THE EXECUTION DAEMON As mentioned above, each machine that may host one or more application replicas should be running an execution daemon. To start the execution daemon, you may issue the following command on the command line of each of your hosts: ant execdaemon Alternatively, you may wish to make the execution daemon a permantent part of the boot procedure of your machines, so that it will be available every time your machines have rebooted. The execution daemon is a very light-weight process, and only listens for requests to create replicas on the local machine. Thus, while not creating a replica the execution daemon consume very little memory and CPU capacity. 6.2. STARTING THE REPLICATION MANAGER Starting the replication manager is slightly different from the other applications provided with Jgroup/ARM. It works by invoking the following command: ant replicamanager However, note that the command need not be executed on a machine running an execution daemon. This is because the replicamanager target specified in the build.xml file forces the replicamanager to do a bootstrap. That is, it will use its own replica distribution mechanism to determine on which machine it should install itself. This means that when invoking the above command above on machineX, the replicamanager replicas will be created on a set of machine(s), different from machineX, for instance machineY and machineZ. Also the replicamanager replicas, could potentially be bootstrapped during the boot procedures of each machine of your system. However, currently we do not support this feature. Currently, the replicamanager have only been tested with a single replica instance. 6.3. STARTING AN APPLICATION USING THE REPLICATION MANAGER For the purpose of starting an application through the replication manager, we provide a simple management client. Currently, it has only two applications hard-coded into the source. Future versions will provide graphical user interface for starting applications by using the management client. To start the management client, two targets are provided in the build file: ant mc-repl Starts the replication server application on the required set of hosts. ant mc-perf Similarly, mc-perf will start the performance server on the number of hosts specified in the applications.xml configuration file. Basically, the two applications are more or less equal in functionality. They both allow the performance client to perform method invocations on the server. We use two separate implementations for testing the distribution mechanism. 7. THE JINI-BASED HELLOSERVER EXAMPLE As of Jgroup version 1.1, it is possible to register server groups on a Jini-compliant lookup service besides on the dependable registry service. Jgroup includes a modified version of reggie, the Jini lookup service. This service is code-named "greg", which stands for "Group-enhanced REGgie". When greg is running, servers belonging to a group may register themselves on it and have a group proxy built from their registration. In order to run greg, several steps must be taken. First of all, you need to start the RMI activation daemon rmid. This is accomplished as follows: rmid -J-Dsun.rmi.activation.execPolicy=none Then, a web server must be run in order to serve requests for Jini class files, using the following build target: ant httpd Finally, the greg service itself must be started by typing: ant greg Once you have started greg, you may start the Jini-based hello server example by typing: ant jhelloserver and ant jhelloclient 8. DEBUG LOGGING Please note that Jgroup/ARM, in particular the lower layer (mss), logs a large amount of data to file (depending on how it is configured). Thus, when running an application for a long period of time, it is a good idea to either configure the logging mechanism so as to log only the most important items. This is to limit the size of log files. Alternatively, you may wish to turn off logging completely. Configuring logging for Jgroup/ARM involves editing the Log4j XML configuration file config/logging.xml. Please refer to the Log4j documentation for details on how to configure logging. Turning off logging completely leaves only important warning and error messages, while all other debug code is removed from the compiled byte code files (assuming you are using an optimizing compiler, like Jikes). To turn off logging completely, run the following target: ant debugoff To turn it logging back on again, run the following target: ant debugon Note that both these targets will cause the entire Jgroup/ARM distribution to be rebuilt. All log files are stored in the log/ directory, and you may delete them as you see fit. You may also use the build target: ant cleanlog 10. ADVANCED FEATURES AND DETAILS Note that, if performance is of essence to your system, you may want to limit the number of entries in the system configuration (config.xml) to a minimum for your system. This is because each host entry adds 14 bytes to a number of messages being exchanged between Jgroup nodes. 11. TROUBLESHOOTING ** THE 'helloserver' WILL NOT BIND TO THE DEPENDABLE REGISTRY. ** The 'helloserver' application should always report back the following to the console: Server ready and bound to the dependable registry If this does not happen, examine the log file or any other output from Jgroup (depending on the logging granularity chosen.) If you find a nested exception java.rmi.ServerException: RemoteException with the following main exception: java.io.InvalidClassException. This typically indicates that some class have different serialVersionUID in the local and remote versions of that class. This may occur if Jgroup was built with different compiler versions on your various sites (including hosts). To check your compiled code, you can run the following commands (replace the class jgroup.util.ByteVectorOutputStream below with the class that is reported as invalid in the exception): cd serialver jgroup.util.ByteVectorOutputStream This should always report the same number for all sites in your distributed system. So the solution is to ensure that all hosts in your system use the same compiler version.