SeisNetWatch Installation

Introduction
Free Software / Source Available
Requirements
Getting Started
NSI Setup
GUI Client Setup
Agent Setup

Last Updated June 25, 2012

Introduction:

This is the installation manual for the SeisNetWatch System for seismic network monitoring. It consists of a three tier system of agents, server, and end-user clients that allow network operators to monitor the state of health of a seismic network's digital acquisition software in real time.

The five components that make up a SeisNetWatch system are described below:

Collection agents: Applications that collect station status information parameters and send them to the Network Station Information (NSI) server.
Network Station Information (NSI) server: The central collection, control, and decision making software.
SeisNetWatch GUI client: A browser applet or java application that displays the information provided by the NSI Server.
Control agents: (optional) Applications that allow authorized users to modify the operation of stations' acquisition software.
Emailer client: (optional) A daemon program able to send network status reports via email and alert messages to pagers and cell phones.

Included in the SeisNetWatch distribution are the NSI server, GUI client, and example files that demonstrate how they are run. Also included is a collection agent simulator and a control agent simulator, which are helpful for testing the system and demonstrating its capabilities. A simulation version of the system is ready to run "out of the box." We highly recommend that you run the simulation first.

This manual provides the basics of how to install and get the software running. It is accompanied by a configuration map document that details the specifics of the configuration and initialization files necessary to run the system.

[Back to Top]

Free Software / Source Available:

This software is free to all academic institutions. Other users must contact us for licensing terms. If you use the software you must give credit to its authors at ISTI.com by providing a web link to us on your SeisNetWatch web pages.

If you are interested in running this software, please contact us and we would be happy to help you with an installation. It is also possible to have new agents designed or new features implemented in the system.

The source code for the server, the GUI client, and some agents are available upon request. Any changes must be distributed in source form and must be checked back into the CVS repository at ISTI.com.

[Back to Top]

Requirements:

The SeisNetWatch NSI server and agent simulators were written in Java, and can run on any operation system upon which Sun's Java Virtual Machine (JVM) version 1.4 or later is implemented.

The collection agents were, in general, written in C++ to allow them to interface with existing acquisition software packages (like 'comserv' and 'Earthworm').

The GUI client was written in Java, and may be run as an applet or application. Running as an applet, it operates within an Internet browser that either supports Java version 1.4 (or later), or has Sun's Java Runtime Environment (JRE) version 1.4 (or later) plug-in installed. (Use of the plug-in requires special HTML code in the web document used to startup the applet, examples of which are included in this distrubution.) The applet is certified to run in the Netscape version 4.7 browser. Running as application, the requirements are the same as those for the NSI server (with the addition of necessary graphics support in the operating system).

[Back to Top]

Getting Started:

The SeisNetWatch package is distributed in an archive that may unpacked into a directory of the user's choice. The following subdirectories make up the package:

bat - Example batch files, for use with Windows operating systems.

bin - Example script files, for use with Unix-based operating systems.

client - Files related to the GUI client applet / application.

conf - Example configuration files for the SeisNetWatch server (and agent simulators).

docs - Documentation files.

emailer - Files related to the SeisNetWatch 'Emailer' client application.

examples - Miscellaneous example files.

jars - Java archive files needed to run the SeisNetWatch server (and agent simulators).

log - The directory where SeisNetWatch log files will be written to.

For test purposes, it is recommended that a SeiNetWatch simulation system be tried out. This may be done as follows:

Using a Unix-based operating system: Change to the 'bin' directory. All the files in this directory must be marked as executable (via a command like 'chmod a+x *'). Run the script file 'runAllSim'. Once the NSI server is running, the GUI client application may be started via the script file 'runGUIClient'.

Using a Windows operating system: Change to the 'bat' directory. Run the batch file 'runAllSim.bat'. (Note that on some Windows 95/98 systems, running the NSI server and both the collection and control agent simulators proves to be problematic. In this case, use the batch file 'runAllSim_noCTA.bat', which leaves out the control agent simulator.) Once the NSI server is running, the GUI client application may be started via the batch file 'runGUIClient.bat'.

The 'runAllSim' command first starts up six CORBA event channel applications, which are used to communicate with the NSI server. Each one should display a message to the console containing "IOR:" followed by a long string of characters. The 'runAllSim' command then starts the agent simulators and the NSI server. If all goes well, these should generate no messages to the console.

The 'runGUIClient' command should bring up the graphical client interface, showing a "reactor panel" of station buttons. All the functions of the GUI client interface may then be exercised.

When running as an application, the GUI client may be terminated via the "Exit" button. If the NSI server and agents are running in console windows, they may be terminated by entering the "terminate" command, or by hitting <Ctrl-C>. When the event channel applications are running in console windows, they may be terminated by hitting <Ctrl-C>. When any of these applications are running the background, they must be terminated via an operating system command like "kill #".

After Testing:

After you have tested the system you must customize the install to run for your site. The order in which you must configure and run the system for the first time is listed below:

Configure the NSI server files (NSI.conf, orb.config, ruleset.ini)
Start the event channels
Start the NSI server
Configure the Agents
Start the Agents
Configure the GUI client
Start the GUI client
Try it out...

After you have a running system, any component may be started or stopped at any time. You will most likely want to setup automatic scripts to start the event channels and NSI server on the host after a reboot.

[Back to Top]

NSI Setup:

Users will generally connect to the SeisNetWatch system using GUI client applets running on an Internet browser. When the SeisNetWatch NSI server starts up, it writes its CORBA IOR address string to a file (usually named 'gui_acceptor_ior.ref') that is accessible to the GUI client applets via an HTTP connection. As such, the SeisNetWatch NSI server usually needs to be running on the host with the web server.

CORBA event channels are used to facilitate communication between the agents and the NSI server. Each event channel runs as a Java application in a separate process, and makes use of a unique port number. The port numbers are configured in two places (that must contain the same numbers): In the 'startEventChannels' script (or batch) file are the commands used to startup the event channel processes; and each command contains an '-OAport' parameter followed by the port number for that channel. The other place is in the 'orb.config' file in the 'conf' directory. The agents will also need to know the orb.config file IP and port number selections. In the following example line from an 'orb.config' file, the port number 10001 is configured:

ooc.service.CaRequestEventService=iiop://localhost:10001/DefaultEventChannel

For most installations, the port number values will not need to be changed. If, however, a second NSI server is run on the same machine, it will need to have a unique set of port numbers configured.

Note that localhost is used here, but if the agents were to be located on a separate host from the NSI server (remember this is a distributed system), you should use the fully qualified domain name for the NSI host (i.e. bob.serverdomain.com).

The SeisNetWatch NSI server uses a configuration file to set up many of its operating parameters. In the simulator system provided in this distribution, the 'NSI_sim.conf' file (in the 'conf' directory) is used to configure the simulation on Unix systems (Solaris/Linux). For a deployed SeisNetWatch system, this file should be copied, renamed and customized. Some of the more important parameter settings include:

baseDir: Sets the base directory of the SeisNetWatch system. Under this directory are the 'bat', 'bin', 'conf', 'jars' and 'log' subdirectories. The relative path value of "../" will work as long as the current working directory is one of the subdirectories of 'baseDir' when the NSI server is started.

daemon: If 'true' then the server is run in 'daemon' mode, where no further console I/O is used. This is desirable when the server is run in the background without a console window.

rulesetFileName: Sets the name of the rule set file used by the NSI server to determine the performance levels of stations and their parameters. In the simulator system provided in this distribution, the 'ruleset_sim.conf' file (in the 'conf' directory) is used configure the simulation rule set settings. For a deployed SeisNetWatch system, this file should be copied, renamed and customized. This file is further described in the configuration map document.

stationsFileName: Sets the name of the stations information file used by the NSI server to associate predefined station names to station-template entries in the rule set file. In the simulator system provided in this distribution, the 'stations_info_sim.conf' file (in the 'conf' directory) is used configure the simulated stations information settings. For deployed SeisNetWatch systems that use predefined station names, this file may be copied, renamed and customized. For deployed SeisNetWatch systems that use dynamically-created stations, an empty file may be used. This file is further described in the configuration map document. NOTE that for EARTHWORM installations where dynamic station discovery is performed, this file is not needed! It can be provided to specify rulesets for given stations AND to provide detailed static station information to end users.

guiAcceptorIORFile: Sets the path to and name of the file containing the CORBA IOR address string (used by GUI clients). The file should usually reside in same HTTP-accessible directory as the GUI-client JAR and HTML files.

orbPortNum: Sets the port number used by the CORBA services of the NSI server. For most installations, this value will not need to be changed. If, however, a second NSI server is run on the same machine, it will need to have a unique set of port numbers configured.

serverName: Sets the 'name' associated with this NSI server. This name is displayed on the main screen of any GUI clients connected.

More information on the NSI server configuration file is available in the configuration map document.

During its operation, the NSI server will write messages to its log file (named via the 'globalLogFileName' parameter). If the 'configFileParsingLogFlag' parameter is set to 'true' then the NSI server will write messages to a separate "parsing" log file (named via the 'configFileParsingLogfile' parameter) during the parsing of the rule set and stations information files. Both of these log files reside in the 'log' directory and can be invaluable in diagnosing configuration problems with the system. We highly recommend that you look at the log output if you have any problems.

[Back to Top]

GUI Client Setup:

For GUI clients to be run as an applets, a web directory where the applet '.html' and '.jar' files can be accessed from is needed. To restrict client access to authorized users, this can be a "secure" web directory accessible only via a user name and password. The NSI server should be configured to, upon start up, write its CORBA IOR address string to a file (usually named 'gui_acceptor_ior.ref') in this same web directory.

The following files are provided in the 'client' directory of this distribution:

client.jar - The Java archive for the GUI client when when as an applet.

application.jar - This Java archive may be used to run the GUI client as a Java application.

Client.ini - A sample configuration settings file that may be used by the GUI client.

When running as an application, the GUI client will use the "Client.ini" file in its working directory if the file is found. As of GUI client version 1.24, when running as applet the program will use the "Client.ini" file in its web directory if the file is found. The 'configFileName' parameter may be used to specify the path to and name of the configuration settings file to be used.

The GUI client requires a version 1.4 (or later) Java Runtime Environment (JRE) to operate in. Most current browsers do not have this level of native support, and so a Java plugin must be used to run the applet. Samples of the HTML document code needed to do this may be found in the example files listed below.

When an HTML document referencing a JRE plugin is used in a browser that does not have the plugin installed, a dialog window appears asking the user to download and install the plugin. After this one-time action is completed, the applet will execute.

The following subdirectories of example files are provided in the 'client' directory:

noplugin - For browsers that do not require a JRE plugin.

v1.2.2plugin - For browsers using the JRE version 1.2.2 plugin.

v1.3.1plugin - For browsers using the JRE version 1.3.1 plugin.

In each of the above subdirectories is an analogous set of HTML document files used to the run the GUI client applet. Their various attributes are described as follows:

client.html - Displayed size of 800 x 550 pixels.

client_larger.html - Displayed size of 900 x 800 pixels.

client_percent.html - Displayed size relative to the size of the browser window.

For any of these 'client' HTML documents to work, they must be copied in the same directory as the 'client.jar' file.

More information on the GUI client may be found in the GUI Client Help document.

[Back to Top]

Agent Setup:

A number of SeisNetWatch agents are provided with this distribution and more are being developed (contact us to find out details or to have custom agents developed for your instruments or data acquisition software.) SeisNetWatch agents perform specific data gathering tasks and need to be configured individually for the data acquisition system being used (e.g., COMSERV, or Earthworm). Refer to the agent-specific documentation for details on configuring and running the agents. (Check the main SeisNetWatch Documentation index for more information on the agents.)

[Back to Top]

Click here to vist the ISTI home page

[Back to Top]