The Real-Time Visualization Software allows you to monitor a connection-oriented network (e.g. an ATM network) that uses IP. It draws a map of your network, complete with hosts, switches, and the physical and virtual connnections between them.
Figure 1: Visualization Components
Figure 1 shows the components of the system. A data collection host collects data about the network under test; the display process uses these data to draw a map of the network. There can be multiple copies of the display process, and they can access the data either directly or through a WWW server. In either case, the display process users have the same view of the network and the same control over the display.
Figure 2: Sample Network Dislay
Figure 2 shows an example of a network display. The squares represent network nodes. Black lines between nodes represent physical connections; colored lines represent VCCs (see Section 3.4.6 for a discussion on the meanings of the various colors).
As shown in Figure 3, the main parts of the Real-Time Visualization Software are a data collection and analysis process and a display process. The data collection and analysis process finds the network nodes, figures out the connections between them, and passes this information along to one or more display processes. The display process displays a map of the network under test, including network nodes and connections, and allows you to control some aspects of the display.
Figure 3: Visualization System Overview
Data flow from left to right in Figure 3. The data collector extracts information from nodes in the network under test with SNMP queries. It puts the information that is gathered into collector updates and writes them to the data analysis module or to a file, or both. Statements in the configuration file control the disposition of the collector updates.
The data analysis module reads the collector updates (either directly from the data collector or from a file) and uses the information in them to build a model of the network under test. It puts information describing the model into model updates and writes them to the display process or to a file, or both. Statements in the configuration file control the disposition of the model updates.
The display process reads the model updates (either directly from the data analysis module or from a file) and draws a map of the network under test. The user chooses the source of the model updates and has control of the appearnce of the display (see Section 3.4). Under user command, the display process can save a GIF image of the displayed network diagram.
The data collection and analysis process is responsible for gathering information about the network under test and assembling it into a coherent model of the network. As shown in Figure 3, it contains two main parts: the data collectors and the data analysis module.
When the data collection and analysis process starts, it reads the configuration file. Then it starts up the requested number of data collectors, each as a separate Java thread, and a data analysis thread.
The data collectors gather information from nodes in the network under test with SNMP queries. They use information from the SNMP responses to create collector updates. These updates are the only means of communication between the data collectors and the data analysis module. The data collectors pass collector updates directly to the data analysis module and can optionally write them to a file. The data collectors only need read access to nodes in the network under test; they will never change SNMP variables.
The data analysis module reads collector updates and uses the information in them to create a model of the network under test, including:
It reports changes in the network model to the display process via model updates. The analysis module writes model updates either directly to one or more display processes over socket connections or to a file, or both.
You only need to run one instance of the data collection and analysis process to discover the extent of a given network. It can report information from that network to a number of different display processes, so you can run a single instance of the data collection process and allow any number of users to view the network.
The data collection and analysis process must run as a Java application. That is, it must be run under a Java Virtual Machine (JVM) under the direct control of the data collection host's operating system. It cannot run as an applet under a Web browser. See Section 3.1 for instructions on running the data collection and analysis process.
The display process displays the network as reported by the data collection and analysis process. It allows you to control various aspects of the display, including:
The display process reads model updates (either from the data collection and analysis process or from a file) and displays a map of the network under test on the user's display. Multiple display processes can be reading and displaying the same data simultaneously. Since each display process is controlled by its user, each can have a different view of the network.
The display process can run either as a Java application or as an applet. That is, it can run under a JVM under the viewing host's operating system or it can run under a JVM provided by a Web browser (e.g. Netscape Navigator or Microsoft's Internet Explorer). The display process need not be running on the same machine as the data collection and analysis process. See Section 3.3 for instructions on running the display process.
Note that one restriction on Java applets is that they are not allowed to make socket connections except to the host running the server that launched the applet. To allow for the Web server and the data collection and analysis process to be run on different hosts, the package includes a socket relay program. This program listens for socket connections from a display process and, when one is made, makes a second connection to the data collection and analysis process. All data that arrive from the data collection and analysis process are forwarded to the display process. See Section 3.5 for instructions on running the socket relay program.
For the data collection and analysis process:
For the display process run as a Java application:
For the display process run as an applet:
Parts of the Real-Time Visualization Software are from sources other than Network Computing Services, Inc. Specifically, publicly-available free software packages are used for SNMP and for writing GIF and JPEG files. They are included in the Real-Time Visualization Software source distribution. See Appendix B for more information.
Instructions for installing the Real-Time Visualization Software package can be found in the Installation Guide.
You run the data collection and analysis process under an instance of a Java Virtual Machine (JVM) under the control of your operating system. The command line format (at least for Unix and MS-DOS machines) is:
java -classpath <class paths> VisiCollector <config file> <run name>
The class path must include directories or .jar files that contain:
classes.zip),VisiCollector directory),VisiModel directory or VisiModel.jar),snmp.jar).<config file> specifies the name of the configuration file for the data collection and analysis process. This file is discussed in Section 3.2.
<run name> is an arbitrary name that identifies the instance of the data collection process. It is used when creating a file of collector updates (a .vcu file) or model updates (a .vmu file) that provide a record of the events in the network under test during the run.
The configuration file contains information the data collection process needs to do its job. The statements that can appear are:
net <network name>
collectors <number of collectors>
password <password to try>
node <dns name>|<ip address> [<node password>]
collect_input net [save [<directory name>]
collect_input file <file name>
model_output listen [<port number>]
model_output save [<directory name>]
log_level <level>
mask_addresses <boolean>
map <prefix> <mask_name>
The net configuration statement provides a name for the network under test. The format is:
net <network name>
The network name can be an arbitrary string. The default value is "MyNet." The network name is passed to the display process and appears in the title of the display window. There can be only one net statement per configuration file.
The collectors configuration statement specifies how many parallel data collectors the data collection process is to deploy. The format is:
collectors <number of collectors>
The data collection process can use multiple data collectors, each running as a separate Java thread. This speeds up the discovery process and data collection because the multiple threads work in parallel to gather data.
The default value is 3. There can be only one collectors statement per configuration file.
The password configuration statement specifies an SNMP community string that will be used to when reading information from nodes in the network. The format is:
password <password>
In order to extract information from a network node, the data collection process must present the node with a valid community string. In many networks, the same community string is used on all nodes. But in a network whose nodes have different community strings, multiple password statements will be necessary in order to ensure that the data collection process has access to information from all nodes.
The password can be an arbitrary string. The default value is "public." There can be as many password statements as necessary in the configuration file.
The node configuration statement specifies a node in the network under test that can be used as a starting point for finding out the topology of the network. The format is:
node <dns name>|<ip address> [<node password>]
The data collection process needs a starting point from which it can learn about other network nodes. The starting point can be a host or a switch, and there can be multiple starting points. Adding more node statements should speed up the discovery process.
The default value is "localhost," the host on which the data collection process is running. There can be multiple node statments in the configuration file.
The collect_input configuration statement tells the data analysis module where to look for input. The formats are:
collect_input net [save [<directory name>]
collect_input file <file name>
There are two forms: net and file. The net form tells the collection process to collect data from devices on the network. If the optional save keyword is present, the data collection process will save the collector updates in a file in the designated directory. The file name will be the run name from the command line with the extension .vcu appended.
The file form tells the collection process to read collector updates from the designated file.
The default value for the net form is to not save the collector updates; the default value for the file form is the standard input file. There can be only one collect_input statement in the configuration file.
The model_output configuration statement tells the data analysis module what to do with the model update objects that it produces. The formats are:
model_output listen [<port number>]
model_output save [<directory name>]
There are two forms: listen and save. The listen form tells the collection process to listen for connections on the specified port and to send the model updates to the machine at the other end of the connection.
The save form tells the collection process to write the model updates to a file in the designated directory. The file name will be the run name from the command line with the extension .vmu appended.
The default value is for the listen form is port number 14356; the default directory for the save form is the directory in which the data collection process is running. There can be multiple model_output statements in the configuration file.
The log_level configuration statement specifies which types of messages you want the data collection process to log. The format is:
log_level <level>
Valid logging levels are shown in the table below. The level masks can be combined by addition. For example, a logging level of 3 would indicate that both error and warning messages should be logged.
|
Logging Level |
Mask |
|
No logging |
0x0 |
|
Log error messages |
0x1 |
|
Log warning messages |
0x2 |
|
Log informational messages |
0x4 |
|
Log debug type 1 messages |
0x8 |
|
Log debug type 2 messages |
0x10 |
|
Log debug type 3 messages |
0x20 |
|
Log SNMP messages |
0x40 |
|
Log discovery messages |
0x80 |
|
Log queueing messages |
0x100 |
Table 1: Log Message Levels
The default value is 0. There can be only one log_level statement in the configuration file.
The mask_addresses configuration statement specifies whether the addresses of network nodes should be hidden on the display. The collection process uses the first IP address that it associates with a node as the name for the node. If you turn address masking on, you can hide the IP addresses (see the map statement, Section 3.2.9). Valid values for this keyword are 0, 1, yes, no, true, and false.
mask_addresses <boolean>
The default value is true (equivalent to yes or 1). There can be only one mask_address statement in the configuration file.
The map configuration statement specifies a string to take the place of part of the IP address when address masking is turned on.
map <prefix> <mask_name>
The <mask name> will replace the <prefix>, the first part of the IP address. For example, the statement
map 10.1.1 Local
Would cause a host with IP address 10.1.1.2 to be named "Local.2" on the display. If multiple map statements are specified, the collection process will use the longest match that applies when determining masked names for network nodes.
There is no default value. There can be as many map statements as necessary in the configuration file.
The following is an example of a configuration file for the data collection and analysis process.
#
# Sample VisiCollector configuration file
#
# Name for the network
net 'SomeNetwork'
# Number of data collection threads to run simultaneously
collectors 4
# List of SNMP community strings for nodes in the network
password GiveMeData
password MyPassword
# List of nodes for beginning data collection. Can also use
# the form
# node
node SomeNode.SomeDomain.com
# Collect information from nodes on the network and save them
# in a file
collect_input net save
# Make model updates available on a network socket and save them
# in a file
model_output listen
model_output save
Note that collector updates and model updates will both be written to files. Assuming that the data collection and analysis process is started with a run name of MyRun, the files will be named MyRun.vcu (for the collector updates) and MyRun.vmu (for the model updates).
The display process can be run in two different modes: as a Java applicaton or as a Java applet. The following sections discuss the two modes.
To use the display process as a Java application, you run it under an instance of a Java Virtual Machine (JVM) under the control of your operating system. The advantage to running it this way is that it has fewer restrictions: you can connect directly to the data collection and analysis process, and you will be able to save display images as GIF or JPEG files. The command line format (at least for Unix and MS-DOS machines) is:
java -classpath <class paths> VisiDisplay
The class path must include directories or .jar files that contain:
classes.zip),swing.jar), andVisiDisplay directory).When the display process starts, it will open a window on your display and you can use the menus to open a file or a connection to a data collection and analysis process.
To use the display process as a Java applet, you install it on a Web server and run it under control of a Web browser. The advantage to running it this way is that you don't have to install it on the machine of every user who wants to run it: you install it once on the Web server and it is loaded from the server into the user's browser. An APPLET tag such as the following must be included in the HTML file that starts the display process.
<APPLET CODE="VisiDisplay.class" ARCHIVE="<VisiModel.jar>">
<PARAM name="DataDir" value="<directory>">
<PARAM name="VisiCollector" value="<host name>">
<PARAM name="VisiPort" value="<port>">
</APPLET>
The ARCHIVE keyword specifies the location of the Java archive file for the VisiModel package. This package contains the class files for the model updates and a few other common classes that are used by the display process.
There are three parameters that provide information to the display process: DataDir, VisiCollector, and VisiPort. DataDir specifies the name of a directory in which files of model updates are kept. The display process uses this directory as a base for finding files to open.
VisiCollector
VisiPort
VisiCollector is specified. It tells the display process which port to use when it opens the connection to the data collection and analysis process. If it is not present, VisiDislay uses the default port (14356).
Once the display process is running and has opened a window on your display, you can control the display via the menus and by manipulating objects in the window. The changes you make apply only to your copy of the display process; other people who may be viewing data from the same file or data collection and analysis process will not be affected by your choices.
If you are using the display process from a Web browser, you can have it open a connection to a data collection and analysis process when it starts (see Section 3.3.2). But you can always open a file or a new connection to a data collection and analysis process from the File menu. Use File->Open to select a file of model updates to display, or use File->Connect to open a connection directly to a data collection and analysis process.
If you are running the display process as a Java application, you can save the image in the display window as a GIF or JPEG file. Use File->Save as GIF or File->Save as JPEG to choose a file name and save the image. This function is not available when you use the display process from a Web browser, because Java applets are not allowed to write files on their host machine.
You can end your display session and shut down the display process by selecting File->Exit or by using the "close window" function of your window manager.
You can manipulate objects in the display window, and you can get detailed information about them. To move a network node, put the cursor on it, press the mouse button, and drag it to a new location. Its physical and virtual connections will stretch to stay with it. If automatic positioning is on, though, it may pop back to its original position when the display process repositions the display. Some reasons for repositioning are:
When you put the cursor on a network node (the cursor will change to a pointing hand), the node's name appears at the bottom of the display window. You can then get detailed information about the node by clicking the mouse button. A window will appear with information about the node. If the node is an ATM switch, it will have buttons that allow you to get detailed information about each port on the switch.
You can get detailed information about a VCC by putting the cursor on the VCC line (the cursor will change to a pointing hand) and clicking the mouse button. A window will appear with information about the VCC. More than one window may appear if the cursor is close to more than one VCC line, or if VCC lines are superimposed on each other.
You can create a display configuration to help control the appearance of the display. A display configuration allows you to:
The display process can automatically select positions in the display window for nodes in the network. But you may want to select positions yourself. You can do this on a loose basis by defining areas, or you can select fixed positions for the nodes by turning off automatic positioning. Unselect the Configuration->Automatic positioning checkbox to turn off automatic positioning. If you turn off automatic positioning, though, any new network nodes that are discovered will not appear on the display; the manual positioning algorithm does not know where to draw them.
An area is a rectangular portion of the display window that selected network nodes will always be drawn inside. Each area has a name. The size of an area is relative to the size of the display window; if you resize the window, the sizes of the areas will change, too. Methods of creating and modifying areas are discussed below.
You can open an existing configuration file by using Configuration->Open. If the display process is running as a Java application, you can create or modify a configuration file by using Configuration->Save or Configuration->Save as. If you want to get rid of all the areas, you can use Configuration->Clear.
To create an area, use Configuration->New area. The cursor will change to a crosshair and you can set the position and size of the area by dragging the mouse. The display process will ask for a name for the area when you release the mouse button. If you name an area "Default," it will be home to nodes that aren't part of other areas; no other names have any special significance.
You can select an area by clicking in it. You can move an area by dragging inside it (but outside any nodes that are in it). You can resize an area by selecting it and dragging one of the selection boxes that appear on its corners and edges. You can rename an area by selecting it and using Configuration->Rename area. You can delete an area by selecting it and using Configuration->Delete area.
You move network nodes into an area by dragging them into the area. If automatic positioning is in effect, you can drag an ATM switch into an area and all its connected hosts will go into the area with it; dragging any other type of node into an area will move it temporarily, but the node will not remain in the area permanently.
You can control certain display parameters using View->Set up view. When you select this menu entry, a window as shown in Figure 4 will appear; you can choose how you would like the parameters set.
In the first panel, you can choose whether a number of network elements are drawn. They are:
If the checkbox for an item is set, the display process will draw items of that type on the display; if the checkbox is not set, items of that type will not be drawn, even when they are present in the network.
In the second panel, you can choose which types of VCCs are displayed, based on their signalling type. This is helpful if, for instance, you want to see only VCCs that were established using the UNI signalling protocol. The selections in this panel are effective only if Color VCCs by signalling type is selected in the fourth panel. The small colored boxes that appear next to the checkboxes show the colors that will be used when drawing the corresponding VCC types.
In the third panel, you can choose which types of VCCs are displayed, based on their usage. These selections are not useful yet, because the data collection and analysis process does not yet set the usage type in the VCC.
In the fourth panel, you can choose how VCCs are colored. If you choose Color VCCs by signalling type, the VCCs selected in the second panel will be displayed in the color indicated in the panel. If you choose Color VCCs by owner, all VCCs will be displayed as type "Unknown," because setting the owner for VCCs is not yet implemented by the data collection and analysis process. If you choose Color VCCs by data rate, the VCCs will be shaded from red to purple, with representing low utilization and purple representing high utilization. If you choose Color VCCs by age, the VCCs will be shaded from white to red, with white representing an age of zero and red an age of 20 minutes or longer.
If you press the OK button, the settings you have chosen will take effect and the network view window will be closed. If you press the Apply button, the settings will take effect and the window will remain open to allow you to make further changes. If you press the Cancel button, the window will be closed and the settings will not be changed.
You can get a summary of information about the network by using View->Network information. A window will pop up showing the name of the network and counts of various network elements.
You need to use the socket relay program when:
You run the socket relay program under an instance of a Java Virtual Machine (JVM) under the control of your operating system. A single copy of the socket relay program can serve multiple display processes, but only one data collection and analysis process. You will have to have the socket relay program running whenever the data collection and analysis program is running. The command line format (at least for Unix and MS-DOS machines) is:
java -classpath <class paths> SocketRelay <host> [<collection port> [<local port>]]
The class path must include directories or .jar files that contain:
classes.zip),<host> specifies the name or IP address of the host where the data collection and analysis program is running.
<collection port> specifies the port number for the data collection and analysis process. If it is not specified, the default port number (14356) is assumed.
<local port> specifies the port number on the Web server that the display process should connect to. If it is not specified, the default port number (14356) is assumed.
You can configure the data collection process to save the information that it learns via SNMP queries. To save the data, use the save keyword on the collect_input configuration command (see Section 3.2.5). The data are saved as collector updates; the collector update file consists of serialized Java CollectorUpdate objects. You can analyze this file later by specifying its name in the collect_input configuration command.
NB-Serialized objects contain a signature; the signature of an object being read must match the signature expected by the reader. This means that if you save a file of collector updates, then change the definition of the update object (by modifying the source and recompiling), you will no longer be able to read the file you saved.
You can configure the data analysis process to save information about the network under test. To save the data, use the save keyword on the model_output configuration command (see Section 3.2.6). The data are saved as model updates; the model update file consists of serialized Java ModelUpdate objects. You can display this file with VisiDisplay by choosing File->Open and selecting the file.
NB-Serialized objects contain a signature; the signature of an object being read must match the signature expected by the reader. This means that if you save a file of model updates, then change the definition of the update object (by modifying the source and recompiling), you will no longer be able to read the file you saved.
The Real-Time Visualization Software package uses some code that was written outside of Network Computing Services, Inc. The distribution package includes Java archive files (.jar files) for these packages, but the source is not included. This section tells you where you can find the source for these redistributed packages and what licenses are granted by the authors.
The Real-Time Visualization Software package uses software from Westhawk Ltd. to gather information via SNMP. The Westhawk SNMP package is used by the data collector, so it is a necessary part of the Real-Time Visualization Software package. The source and license can be found at http://www.westhawk.co.uk/. The source code contains the following copyright and license information:
/*
* Copyright (C) 1996, 1997 by Westhawk Ltd (www.westhawk.co.uk)
*
* Permission to use, copy, modify, and distribute this software
* for any purpose and without fee is hereby granted, provided
* that the above copyright notices appear in all copies and that
* both the copyright notice and this permission notice appear in
* supporting documentation.
* This software is provided "as is" without express or implied
* warranty.
* author <a href="mailto:thp@westhawk.co.uk">Tim Panton</a>
*/
/*
* Copyright (C) 1996, 1997, 1998 by Westhawk Ltd
* <a href="www.westhawk.co.uk">www.westhawk.co.uk</a>
*
* Permission to use, copy, modify, and distribute this software
* for any purpose and without fee is hereby granted, provided
* that the above copyright notices appear in all copies and that
* both the copyright notice and this permission notice appear in
* supporting documentation.
* This software is provided "as is" without express or implied
* warranty.
* author <a href="mailto:thp@westhawk.co.uk">Tim Panton</a>
*/
The Real-Time Visualization Software package uses software from ACME Laboratories to save images as GIF files. The ACME package is only needed when VisiDisplay is run as a Java application, and is only used when writing a GIF file. The source and license can be found at http://www.acme.com/. The source code contains the following copyright and license information:
// Copyright (C)1996,1998 by Jef Poskanzer <jef@acme.com>. All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions
// are met:
// 1. Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
// 2. Redistributions in binary form must reproduce the above copyright
// notice, this list of conditions and the following disclaimer in the
// documentation and/or other materials provided with the distribution.
//
// THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
// ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
// ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
// FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
// DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
// OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
// HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
// LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
// OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
// SUCH DAMAGE.
//
// Visit the ACME Labs Java page for up-to-date versions of this and other
// fine Java utilities: http://www.acme.com/java/
The Real-Time Visualization Software package uses software from James R. Weeks at BioElectroMech to save images as JPEG files. The JPEG package is only needed when VisiDisplay is run as a Java application, and is only used when writing a JPEG file. The source and license can be found at http://www.obrador.com/. The Web site includes the following copyright and license information:
The JpegEncoder and its associated classes are Copyright © 1998, James R. Weeks and BioElectroMech. This software is based in part on the work of the Independent JPEG Group.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions, all files included with the source code, and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.