This guide explains how to install the Real-Time Visualization Software package. For further information about the package and how to run it, see the User Guide.
Java programs can run on a wide variety of platforms; indeed, this is one of Java's strengths. This means, however, that it is possible to install and run the Real-Time Visualization Software package on a number of systems that support a number of different sets of utilities and with which the authors have no experience. This Guide, then, can only give instructions in broad terms. For instance, we may tell you to copy a set of files into some directory; we cannot give exact instructions (e.g. commands or window operations) for the wide variety of systems that support Java.
This Guide uses the Unix convention for directory and path names. For example, we write visi/Src/VisiModel to denote the directory named VisiModel within the directory named Src within the directory named visi. We use the terms "directory" and "subdirectory" more or less interchangeably.
For the data collection and analysis process:
For the display process run as a Java application:
For the display process run as an applet:
The Real-Time Visualization Software package is distributed in two different formats: tar format and zip format. Tar is usually present on Unix systems and zip was originally written for MS-DOS, but there are now versions of both programs for many operating systems. In either case, the distribution file contains a number of directories that contain the Java source code, Java class files, and documentation for the package.
You will need to unpack the software with some version of tar or zip. For example, you might use the command:
tar xvf visi.taror
pkunzip visi.zipIn either case, unpacking the software will create a new directory called visi. The visi directory contains three subdirectories: Doc, Src, and Class. The Doc directory includes the User Guide, this Installation Guide, some examples of configuration and HTML files, and documentation for the Java objects that make up the package. The Src directory contains the Java source code for the package, including source code for three free software packages that the Real-Time Visualization Software package uses. The Class directory contains the Java class files (produced by compiling the contents of the Src directory) that implement the Real-Time Visualization Software package. Class files are provided in two formats: the .class files themselves are contained in subdirectories inside the Class directory, and there are Java archive files (.jar files) that contain the bundled .class files. For example, you will find a VisiModel subdirectory containing a number of .class files; you will also find a VisiModel.jar file that is a Java archive of the .class files in the VisiModel subdirectory. The .jar files are provided as a convenience for installing the package.
You may want to install the Real-Time Visualization Software package differently depending on how you want to use it. This section explains several installation options based on different modes the software can be used in. Instructions for running the software can be found in the User Guide.
Figure 1: Real-Time Visualization Software Overview
Figure 1 shows how the parts of the software interact. The software is run as two separate pieces: a data collection and analysis process and a display process (each of these contains a number of concurrent Java threads). Depending on the structure of your network and the resources you have available, you may want to run both processes on the same host or on different hosts. You also have the option of running the display process from a Web browser or as a native Java application.
Within the Src and Class directories, you will find the following subdirectories:
Acme
JPEG
snmp
SocketRelay
VisiCollector
VisiDisplay
VisiModel
VisiCollector, VisiDisplay, and VisiModel contain the code that implements the Real-Time Visualization Software package. VisiCollector contains code for the data collection and analysis process, VisiDisplay contains code for the display process, and VisiModel contains code that is used by both VisiCollector and VisiDisplay, and for communication between them. Snmp contains the SNMP code that the data collection process uses to extract information from nodes in the network. Acme and JPEG contain code that saves images as GIF or JPEG files; they are used by the display process. SocketRelay contains code that is used on Web servers under certain conditions, see Section 3.4.
Figure 2: Single-Host Configuration
The simplest configuration for running the Real-Time Visualization Software is to run both the collection and display processes on the same host, as shown in Figure 2. For this configuration, you need only unpack the software and run the two processes (instructions for running them can be found in the User Guide).
The most common way the authors expect the software to be used is to have the data collection and analysis process running on one host and the display process on another, as shown in Figure 3.
Figure 3: Two-Host Configuration
In this configuration, the display process can be running either as an applet under a Web browser or as a stand-alone Java application (see Section 3.3 and Section 3.4 for information about these configurations).
You will need to install the following components on the data collection host:
VisiCollector
VisiModel
snmp
Create a visi directory in an appropriate location (e.g. under /usr/local on a Unix system or under C:\Program Files on a Microsoft Windows system) and create a directory visi/Class. If you prefer to use .jar files, copy VisiCollector.jar, VisiModel.jar, and snmp.jar to visi/Class. If you'd rather work with the .class files directly (this might be preferable if you are making modifications to the software), create the directories visi/Class/VisiCollector, visi/Class/VisiModel, and visi/Class/snmp, and copy the contents of the corresponding directories in the distribution to the new directories. Note that the snmp directory contains subdirectories as well as files, so you will need to be sure to copy the entire subtree.
You can use .class files for some parts of the package and use .jar files for others. For example, you might want to install the snmp.jar file in visi/Class but create subdirectories for VisiModel and VisiCollector and copy the .class files to them.
In this configuration, the display process runs as a stand-alone Java application. It is illustrated in Figure 3.
You will need to install the following components on the display host:
VisiDisplay
VisiModel
Acme
JPEG
Create a visi directory in an appropriate location (e.g. under /usr/local on a Unix system or under C:\Program Files on a Microsoft Windows system) and create a directory visi/Class. If you prefer to use .jar files, copy VisiDisplay.jar, VisiModel.jar, Acme.jar, and JPEG.jar to visi/Class. If you'd rather work with the .class files directly (this might be preferable if you are making modifications to the software), create the directories visi/Class/VisiDisplay, visi/Class/VisiModel, visi/Class/Acme, and visi/Class/JPEG, and copy the contents of the corresponding directories in the distribution to the new directories. Note that the Acme directory contains subdirectories as well as files, so you will need to be sure to copy the entire subtree.
You can use .class files for some parts of the package and use .jar files for others. For example, you might want to install the Acme.jar and JPEG.jar files in visi/Class but create subdirectories for VisiModel and VisiDisplay and copy the .class files to them.
You can run the data collection and analysis process on one host and make the display process accessible on the World Wide Web, as shown in Figure 4. The Web server sends the display applet to the user's host, where it runs under the control of a Web browser. Anyone with a Java-capable browser can see the information gathered by the software.
Figure 4: Web Server Configuration
This configuration requires another software component, the socket relay program. The socket relay is needed because a Java applet is constrained from making socket connections to hosts other than the Web server the applet was loaded from. This means that the display process is not allowed to make a connection directly to the data collection and analysis process (unless it is running on the Web server). The socket relay program listens for connections from display processes, when it gets one, it makes a connection to the data collection and analysis process and forwards everything it receives from it to the display process.
You will need to install the following components on your Web server:
VisiModel
VisiDisplay
SocketRelay
Create a visi directory in an appropriate location (e.g. under /usr/local on a Unix system or under C:\Program Files on a Microsoft Windows system) and create a directory visi/Class. If you prefer to use .jar files, copy VisiDisplay.jar, VisiModel.jar, and SocketRelay.jar to visi/Class. If you'd rather work with the .class files directly (this might be preferable if you are making modifications to the software), create the directories visi/Class/VisiDisplay, visi/Class/VisiModel, and visi/Class/SocketRelay, and copy the contents of the corresponding directories in the distribution to the new directories.
You can use .class files for some parts of the package and use .jar files for others. For example, you might want to install the SocketRelay.jar file in visi/Class but create subdirectories for VisiModel and VisiDisplay and copy the .class files to them.
The Acme and JPEG components are not required in this configuration because the display applet is constrained from writing files to the host it is running on. It therefore can't write GIF or JPEG files; the Save as GIF and Save as JPEG options on the File menu are disabled and the Acme and JPEG packages are not used.