Runcontrol BINARIES Readme

June 2006

1. Overview

This is the Readme file for the ZIP archive of the Runcontrol binaries release. The Runcontrol modules contains applications for monitoring and controling experiments of HyperCast overlay networks. The application RunControl is a control console and RunServer is a server application that starts overlay sockets and builds an overlay network.

See the Chapter "Monitor and Control" available from www.hypercast.org for additional information.

2. Extract the ZIP archive

The ZIP archive for the binaries are usually distributed in a file with the name

runcontrol-BINARIES-xxx-yyyymmdd.zip

where xxx is a tag that identifies who created the archive and yyyymmdd is the date when the archive was created. Copy the file to a directory where you want to run Runcontrol, and extract ('unzip') the archive with a utility such as WinZip (on Windows) or the unzip command (on Unix or Cygwin).

NOTE: This package requires that the hypercast.jar is located in the the /lib directory. Should hypercast.jar not be included in the ZIP archive, it can be copied form the /lib directory of a hypercast BINARIES directory.

3. Versions

Java Version: The binaries are compiled to Java version 1.4, and run on a JRE with version 1.4 or higher. (The source files of Runcontrol can be compiled with Java version 1.2 or higher)

Runcontrol Version. The Version program works similarly as in the hypercast module. Assuming that the classpath is set correctly, the Runcontrol version is displayed with:
>java runcontrol.Version

HyperCast Version. The version of the HyperCast module, which is used by Runcontrol, is displayed with:
>java hypercast.util.Version

4. Files in runcontrol BINARIES ZIP file

The contents of the archive is this file, XML configuration files, JAR files, and command scripts.

Directories:

/lib

Directory with required *.jar files

lib/hypercast.jar

Implementation of HyperCast.

lib/runcontrol.jar

Implementation of the RunControl and RunServer applications

lib/xalan.jar

XSLT processor for XML documents (xml.apache.org/xalan-j/)

lib/crimson.jar

XML classes needed for Java version 1.5 (and recommended for Java version 1.4)

lib/bcprov-jdk14-122.jar

Implementation of cryptographic algorithms (www.bouncycastle.org)

/bin

Contains scripts that start applications. The "*.sh" scripts are for Unix/Cygwin shells and are run form the / directory. The "*.bat" scripts are for DOS shells. They can be run by `clicking' on the correspondng files.

cli.sh, cli.bat - starts the commandline interpreter of the RunControl application
gui.sh, gui.bat - starts the the RunControl application with a GUI
runserver.sh, runserver.bat - starts the RunServer application
conf.sh, conf.bat - starts the HyperCast configuration editor to edit HyperCast configuration files
version.sh, version.bat - displays the version of RunContro

XML files:

Monitor.xml - HyperCast configuration file for the monitor of the RunControl application
Portal.xml     - HyperCast configuration file for the portal of the RunServer application
hypercast.xml - HyperCast configuration file for the overlay that is monitored by RunControl/RunServer
location.xml   - address/location mapping of IP hosts (only used by RunControl GUI)
map.xml - location of maps (only used by RunControl GUI)

Readme files:

/Runcontrol-BINARIES-Readme.html - this file

5. Editing configuration files

The provided configuration files Monitor.xml, Portal.xml, and hypercast.xml are set for a configuration where the monitor (in RunControl) and the portals (in the RunServer) communicate over an overlay that runs the NONE protocol (The NONE protocol is a minimal protocol that uses physical addresses as logical addresses), and the overlay built by the RunServers runs the DT protocol that builds a Delaunay Triangulation graph (with random coordinates, buddy list rendezvous, TCP socket adapter, UDP node adapter). The configuration files can be modified to fit any viable overlay configuration.

Remark: The following changes from the default values of the configuration files are noteworthy. In Portal.xml and Monitor.xml, the following holds: /Public/SocketAdapter/ScktAdptTCP/MaximumPacketLength=60000.

All configuration files can be edited using the Configuration Editor which is started with the script conf.sh (or conf.bat), or by editing the XML files directly. The XML files need to be changed as described here:

Monitor.xml

No changes are necessary.

Portal.xml

Change the IP address of the Monitor address to /Public/MonitorAndControl/Portal/MonitorAddress =0.0.0.0:1500:1501.
Replace 0.0.0.0 by the IP address where the RunControl CLI or GUI is running.

hypercast.xml

Change the value of the physical address in the nodeadapter from
/Public/NodeAdapter/NodeAdptUDP/PhyAddr/INETV4AndTwoPorts=0.0.0.0:0:0
to
/Public/NodeAdapter/NodeAdptUDP/PhyAddr/INETV4AndTwoPorts=0.0.0.0:9800:0.
This chnage selects UDP port 9800 as the preferred port number for the the node adapter (Only one overlay socket can actually acquire this port number. All other sockets select another available port number). Change the value of /Node/BuddyList/Buddy/UnderlayAddress/INETv4AndOnePort from "0.0.0.0:0" to "x.y.z.w:9800", where "x.y.z.w" is the local IP address (e.g., 128.100.11.52). (With this choice, the overlay socket that acquired port number 9800 for the node adapter, becomes a buddy in the rendezvous process of the overlay socket.

6. Exercises: Running and Experiment with RunServer and RunControl

6.1. Exercise with RunControl Command Line Interpreter (CLI)

The following example starts a RunServer and a RunControl CLI application on the same host. The example is discussed in the Chapter "Monitor and Control".

Step 1. Change to the directory (/) where the XML files are stored.

Step 2. Edit the files Portal.xml and hypercast.xml as discussed in Section 4.

Step 3. Start a RunServer application with 10 overlay sockets. (The maximum number of overlay sockets on a single system can be much higher, e.g., 500-600 on a Windows system).

Unix/Cygwin shells (On Unix systems, replace semicolons (;) by colons (:)):

>java -cp "lib/hypercast.jar;lib/runcontrol.jar;lib/xalan.jar;lib/bcprov-jdk14-122.jar" runserver.RunServer -ns 10 -pc Portal.xml -sc hypercast.xml

Windows Explorer:
Click on the file runserver.bat in /bin. The script contains arguments that start RunServer application with 10 overlay sockets using the same XML files as above.

Step 4. Start a RunControl CLI application

Unix/Cygwin shells (On Unix systems, replace semicolons (;) by colons (:)):

>java -cp "lib/hypercast.jar;lib/runcontrol.jar;lib/xalan.jar;lib/bcprov-jdk14-122.jar"
commandline.RunControlCLI -mc Monitor.xml

Windows Explorer:
Click on the file cli.bat in /bin. The script contains arguments that start the RunControl CLI application using the same XML files as above.

Step 5. At the command prompt of the application, type the following commands (enter Return after each line).

> list_portals
> list_sockets
> start_sockets
> wait_until_stable
> stop_sockets

The list_portals command displays the status of the RunServer applications. The list_sockets command lists the number of available overlay sockets at the remote RunServer application. The start_sockets commands causes the overlay sockets on the RunServer application to join the The wait_until_stable command pauses until all overlay sockets have stabilized. The stop_sockets commands asks the overlay sockets to leave the overlay network.

Step 6. Use a second computer and start a RunServer as done in Step 3. Repeat the instructions from Step 5 (There is no need to restart the RunControl CLI application

6.2. Exercise with RunControl GUI

Step 1-3: The same steps as in the first exercise.

Step 4: Start a RunControl CLI application as follows:

Unix/Cygwin shells (On Unix systems, replace semicolons (;) by colons (:)):

>java -cp "lib/hypercast.jar;lib/runcontrol.jar;lib/xalan.jar;lib/bcprov-jdk14-122.jar"
commandline.RunControlGUI -mc Monitor.xml

Windows Explorer:
Click on the file gui.bat in /bin. The script contains arguments that start the RunControl GUI application using the same XML files as above.

In the GUI of the application, go to "Select protocol" (above the blue window), select "Delaunay Triangulation". The application is now set to display the (Delaunay triangulation) overlay network that is constructed by the overlay sockets of the RunServer application.

Step 5. Run the same RunControl commands as in the first exercise. Type the commands in the white window at the bottom and press "Run" (or hit ) after each command.

7. Running Scripts in /bin

There is a set of Unix scripts (*.sh) and DOS scripts (*.bat) that can help with starting the RunServer and RunControl (CLI or GUI) applications. Running the scripts instead of the commands may increase the convenience of running experiments.

In Unix/CYGWIN:

bin/cli.sh -mc <configfile>

Starts the command line interpreter of the RunControl application with the specified configuration file (e.g., Monitor.xml)

bin/gui.sh -mc <configfile>

Starts the RunControl GUI application with the specified configuration file (e.g., Monitor.xml)

bin/runserver.sh -ns <number of overlay sockets> -pc <portalconfigfile> -sc <socketconfigfile>

Starts the RunServer application with specified number of overlay sockets, using a configuration file for the portal (e.g., Portal.xml), and the overlay constructed by the RunServer.

bin/conf.sh

Starts the HyperCast configuration editor to edit HyperCast configuration files.

bin/version.sh

Displays the version of the RunControl module.

Windows Explorer:
For each of the above scripts there is a corresponding DOS script (*.bat). The script can be run by clicking on the file in Windows Explorer. The arguments of the *.bat scripts are as follows:

cli.bat: "-mc ../Monitor.xml"
gui.bat: "-mc ../Monitor.xml"
runserver.bat: "-ns 10 -pc ../Portal.xml -sc ../hypercast.xml"
conf.bat: None
version.bat: None

8. Man Pages for RunControl and RunServer

This appendix lists all options available for the applications RunControl CLI, RunControl GUI, and RunServer.

8.1 RunControl CLI, RunControl GUI

java -cp jarfiles commandline.RunControlCLI -mc file1 [-qr retries]
java -cp jarfiles gui.RunControlGUI -mc file1 [-qr retries]

-cp jarfiles

A list of JAR archives that contain the Java programs needed to run the RunControl application. RunControl requires the executables of HyperCast (hypercast.jar), the archive that contains the RunControl application (runcontrol.jar), and the Apache Xalan-Java XSLT processor (xalan.jar), e.g., "hypercast.jar;runcontrol.jar;xalan.jar"

On Windows, replace jarfiles with "hypercast.jar;runcontrol.jar;xalan.jar"
On Unix , replace jarfiles with "hypercast.jar:runcontrol.jar:xalan.jar"

-mc file1

The configuration file for the monitor (e.g., Monitor.xml)

-qt timeout

The timeout values in milliseconds for transmitting request messages by the monitor protocol.

-qr retries

Maximum number of retransmissions for a query transmitted by RunControl.

8.2 RunServer

java -cp jarfiles runserver.RunServer [-ns NumSock] [-start] -pc file1 -sc file2

-cp jarfiles

A list of the JAR archives that contain the Java programs needed to start the RunServer application. RunServer requires the executables of HyperCast (hypercast.jar), the archive that contains the RunServer application (runcontrol.jar), and the Apache Xalan-Java XSLT processor (xalan.jar).).

On Windows, replace jarfiles with "hypercast.jar;runcontrol.jar;xalan.jar"
On Unix , replace jarfiles with "hypercast.jar:runcontrol.jar:xalan.jar"

-ns NumSock

Number of overlay sockets that will be created by RunServer.

-start

Determines if the overlay sockets immediately join the overlay network after they are created. By default, the overlay sockets created by RunServer do not start the overlay network.

-pc file1

Specifies the XML configuration file for the portal (e.g., Portal.xml)

-sc file2

Specifies the XML configuration file for the overlay sockets of RunServer (e.g., hypercast.xml)

-help

Displays the options available for starting RunServer.