Instrumental Software Technologies, Inc.

SeisNetWatch Configuration Map

Last Updated January 17, 2002

1.0 Introduction:

SeisNetWatch is designed as a control and observation tool for seismic networks, to be used by network operators to monitor the state of health of the network and to control the data acquisition software.

This document is a configuration roadmap to the files that the SeisNetWatch system needs in order to run. This is not an installation manual - please refer to the snw_installation document for these details. The specifics of each configuration file are explained in more detail in the documentation for each component.  This document provides a layout of what configuration files need to be created and where they will reside. It uses the configuration of a test server at CalTech for its examples.

The SeisNetWatch system is a three-tiered distributed system of agents, NetworkStationInfo (NSI) server, and GUI front-end client. Agents collect data and control the acquisition software and communicate over the network to the NSI server. The NSI server is the centralized decision making tool that receives the agent's messages and passes on filtered data to the client.

The client is provided as a Java applet (or application) and the NSI server is a Java application. The Collection and Control Agents may be written in C++ or Java. The control agent, written in Java, provides control over shell scripts which change the "usage" of the station. The communications between the agents and the SeisNetWatch server (NSI server) are accomplished using the CORBA Event Service and communication between the client and the NSI are via CORBA objects.

This software is FREE to all academic institutions. If you are interested in running this software, please contact us at isti.com. If you are not a academic institution and wish to use this software, you must purchase a license from ISTI.com.

2.0 NetworkStationInfo (NSI) Server Configuration:

The NSI server is the focal point for all data and is thus the logical component to configure first. The NSI server and the CORBA event channels, which are used for agent-NSI communications, should be running before any other component runs. The NSI has 4 basic configuration files that must be in place before it can be run. These configuration files, are: 'orb.config', 'NSI.conf', 'ruleset.ini', and 'stations_info.ini'. Each of these files should be stored within a specified directory heirarchy which is described below in the next section.

[Back to Top]

NSI File Layout:

The NSI files required for configuration should all be kept together in a single 'conf' directory. In the example file heirarchy, we have a top level directory named for the system being monitored (hotspotNSI/). Beneath this directory we have two sub directories, one for configuration (conf) files and one for logging files (log). Refer to the figure below for a diagram of the file layout in our example:

[Back to Top]

NSI orb.config file:

The SeisNetWatch system uses the CORBA event service to communicate between the agents and the NSI. The NSI and each agent needs to know which ports and addresses the event channels will be running on. Since the NSI is the focal point of all data from the agents, it makes the most sense to have the event channels running on the same host as the NSI. The 'orb.config' file is simply a NAME to IP:PORT matchup for the event channels. An example 'orb.config' file is shown below for a fictious IP address of 172.16.11.2:

ooc.service.CaRequestEventService=iiop://172.16.11.2:10001/DefaultEventChannel
ooc.service.DynAgentEventService=iiop://172.16.11.2:10002/DefaultEventChannel
ooc.service.StatAgentEventService=iiop://172.16.11.2:10003/DefaultEventChannel
ooc.service.CtaMsgEventService=iiop://172.16.11.2:10004/DefaultEventChannel
ooc.service.CtaResultEventService=iiop://172.16.11.2:10005/DefaultEventChannel

This 'orb.config' specifies the names of 5 event channels to which the NSI and agents will attach. The iiop URL is the IP address and port number at which the event channel will run. The 'orb.config' file of the NSI should be propagated to each host which will run an agent that will send data to this NSI.

[Back to Top]

NSI NSI.conf file:

The 'NSI.conf' file is a text file that specifies the configuration parameter settings for the NSI server. The most important parameters of the 'NSI.conf' for the sake of configuration are: 'baseDir', 'orbConfig', 'rulesetFileName', and 'stationsFileName'.

The 'baseDir' parameter points to the root of the 'conf' and 'log' directories. If a 'baseDir' value is not provided, it defaults to "/usr/local/trinetwatch". The 'rulesetFileName' and 'stationsFileName' parameters point to the 'ruleset.ini' filename and the 'stations_info.ini' filename, respectively. The 'ruleset.ini' and 'stations_info.ini' files should be in the 'conf' subdirectory. The 'orb.config' filename can also be specified inside the 'NSI.conf' and it too should reside in the 'conf' directory. An example NSI.conf file is provided below: 

# The configuration file for the NSI server

## Name of program to be displayed.
programName = "SeisNetWatch"

## In baseDir there will be the directories conf and log.  
## Respectively, they hold program 
## configuration files, and log files. 
baseDir = "/home/isti/hotspotNSI/"

## Whether the program should just act like a daemon process and go about its
## work behind the scenes.
daemon = true

## Length of wait between initial request for static parameters from the 
## collection agent and beginning beginning submitting requests for 
## specific stations (seconds).
staticParamsNap = 30

## Total length of time spent collecting information about static parameters 
## from the collection agent(s) (seconds).
gatherSPTimeout = 360

## Client inactivity timeout, in seconds.
inactivityTimeout = 300

## Number of hours of parameter history data to save
historyLengthHours = 2

## The name of the redirected console output file
consoleRedirectFileName = "NSI_console.txt"

## The name of the global NSI log file.  Default location: 
## [baseDir]/log/NSI.log
globalLogFileName = "NSI.log"

## The desired level of message information.  Choices include: NO_MSGS, INFO,
## WARNING, ERROR, DEBUG and ALL_MSGS. The default is ERROR for both the
## logfile and console.
logfileLogLevel = "DEBUG"
consoleLogLevel = "WARNING"

## Used for debugging.  If true a logfile will be produced in the log 
## directory.  The default is false.
configFileParsingLogFlag = "true"

## Used for debugging.  The name of the logfile to use when debugging the 
## config file parsing routines.  The default is 'NSIparsing.log'
configFileParsingLogfile = "NSIparsing.log"

## The name of the ruleset configuration file.  Default is 'ruleset.ini'
rulesetFileName = "ruleset.ini"

## The name of the stations information file.  Default is 'stations_info.ini'
stationsFileName = "stations_info.ini"

## This is the file in which the IOR for the GUIAcceptor is placed.  The entire
## path must be included.  It will need to go in the somewhere in the web 
## servers html or web directory (ie. where all the web documents are located).
guiAcceptorIORFile = "/home/isti/www/gui_acceptor_ior.ref"

## The port number used by the CORBA services
orbPortNum = 1045

## This is the name of the orb configuration file.  It is needed so the event
## channels will work correctly.
orbConfig = "orb.config"

## Here we find the name of the server which this NSI server is representing.
serverName = "hotspot (test server)"

## A general help string will generally be a URL to which the user can refer 
## for help concerning the system.
generalHelpString = "http://www.isti.com/trinet/gui_help.html"


The 'NSI.conf' file parameters are described in more detail in the server documentation.

[Back to Top]

NSI ruleset.ini file:

The 'ruleset.ini' file is a text file that governs the configuration of the NSI usage levels, performance (status) levels, criteria for performance levels, and station "rule set" templates (groups of criteria). Each configurable item is specified by a directive that uses the comserv style notation of square braces [] to denote the beginning of a section.

Usage Levels

The first section of a 'ruleset.ini' files is the [Usages] section, which specifies the usage level mappings (i.e., a number to a name and symbol). For the NSI, the concept of a Usage is simply a "name and number". What a Usage actually is in the data acquisition system is left to the collection agents to define (i.e., in the CalTech TriNet network, we have defined Usage to be a set of data acquisition processes that are currently running or off). The control agent must also know what a usage level maps to. The GUI will notify the control agent, via the NSI, that the end-user wants to change the usage level of a station. The control agent receives the number of the usage level and sends it to a script for action. An example [Usages] section is provided below: 
[Usages]

usageFull                              //name used in this file
{
   name = "Full"                        //name used externally
   value = 3
   color = White
   desc = "Usage Level Full"
}

usageEval                              //name used in this file
{
   name = "Evaluation"                  //name used externally
   value = 2
   symbol = "E"
   description = "Usage Level Evaluation"
}

usageOff                               //name used in this file
{
   name = "Off"                         //name used externally
   value = 1
   symbol = "X"
   desc = "Usage Level Off"
}

usageUndefined                        //name used in this file
{
   name = "Undefined"                  //name used externally
   value = 0
   color = Black
   desc = "Usage Level Undefined"
}
Each [Usages] item contains a usage-tag-name followed by a open bracket, parameters and then a close bracket. The usage-tag-name is used later to tie different criterias to a given usage level. The parameters that must be specified are name, value, symbol (or color), and desc. 'name' is the name that the GUI client will use to refer to a given usage level. 'symbol' is the character used to display the usage level on the "reactor panel" of the GUI client (on the Stations or Subset of Stations tabs); or, alternately, a 'color' value is specified to show a circle symbol. 'value' is a number that describes the usage level and is passed between the NSI and the agents.

Note that a [Usages] section must define an "Undefined" level so that indeterminate usages can be distinguished from any other. The "Undefined" usage level must have a value of 0.

Performance (Status) Levels

Following the [Usages] section the user must specify the Performance Levels. These are listed in a section labelled [Statuses] (NOTE:the original SeisNetWatch implementation called these status instead of performance levels). The [Statuses] section simply maps a name (such as "Good") with a value, color and description. An example [Statuses] section is provided below: 
//Status Level Definitions:

[Statuses]

statusGood                             //name used in this file
{
   name = "Good"                        //name used externally
   value = 3
   color = Green
   desc = "Status Level Good"
}

statusFair                             //name used in this file
{
   name = "Fair"                        //name used externally
   value = 2
   color = Yellow
   desc = "Status Level Fair"
}

statusBad                             //name used in this file
{
   name = "Bad"                        //name used externally
   value = 1
   color = Red
   desc = "Status Level Bad"
}

statusUnknown                         //name used in this file
{
   name = "Unknown"                    //name used externally
   value = 0
   color = Black
   desc = "Status Level Unknown"
}
Each [Statuses] item contains a status-tag-name followed by a open bracket, parameters and then a close bracket. The status-tag-name is used later to reference the given performance level.  'name' is the name that the GUI client will use to refer to a given performance level. 'color' specifies the color associated with the level. 'value' is a number that describes the performance level.

Note that a [Statuses] section must define an "Unknown" level so that indeterminate performance levels can be distinguished from any other. The "Unknown" performance level must have a value of 0.

[Criterias] Section

Any dynamic parameter (with numeric values) provided by a collection agent for a given station can be used in determining the performance (status) level of that station. The means for providing qualifying values for determining performance levels is via the [Criterias] section. In this section of the 'ruleset.ini' file the user specifies a block for each value. The block contains a name, an open bracket {, a number of statements and a close bracket }. The name is that of a dynamic parameter. Enclosed in the brackets {} are criteria-blocks and, optionally a help-string entry which takes the following form: 
 helpString = "text"
where "text" is the help-string text or a URL pointing to a web page.

Each criteria-block contains a block-name, an open bracket {, a number of statements, and a close bracket }. Each criteria-block tends to be associated with a usage level (but not always). This is so that users may specify different criterias depending upon the usage level a station is in (e.g., do you really care about mass position of a sensor if the station is off?). Between the brackets {}, each statement defines a minimum comparison value associated with a status level, and takes the following form: 

 statusname >= ###
where "statusname" is one of the "internal" status-tag-names defined earlier in the file, and "###" is a numeric (or boolean) value. Each numeric value in the criteria-block must be larger than the one before it. When a dynamic parameter value is checked against the criteria-block (in the NSI), the last statement with a value less than or equal to the dynamic parameter value is accepted, and its status level is selected. The "###' value must be one of the following types: An example set of Criterias is provided below: 
//////////////////////////////////////////////////////////////
//Criteria Definitions:

[Criterias]

"Secs Since Last Good Packet"
{
   uFull
   {
     statusGood >= -5
     statusFair >= 10
     statusBad >= 15
   }
   uEval
   {
     statusGood >= -5
     statusFair >= 10
     statusBad >= 15
   } uAnalog
   {
     statusGood >= -5
     statusFair >= 15
     statusBad >= 20
   }
   uOff
   {

     statusGood >= -5
   }
   }
   helpString = "Seconds since last good packet observed at comserv Agent"
}

//////////////////////////////////////////////////////////////
// The following is the Absolute Maximum voltage of a mass position
// the name of the channel can be changed to any channel.

"Mass Pos. (Max-Abs V) UMN"
{
   uFull
   {
        statusGood >= 0.0
        statusFair >= 5.0
        statusBad  >= 10.0
   }
   helpString = "Absolute Maximum Voltage for the Mass Position of the specified channel"
}

"Mass Pos. (Max-Abs V) UME"
{
   uFull
   {
        statusGood >= 0.0
        statusFair >= 5.0
        statusBad  >= 10.0
   }
   }
   helpString = "Absolute Maximum Voltage for the Mass Position of the specified channel"
}

"Mass Pos. (Max-Abs V) UMZ"
{
   uFull
   {
        statusGood >= 0.0
        statusFair >= 5.0
        statusBad  >= 10.0
   }
   helpString = "Absolute Maximum Voltage for the Mass Position of the specified channel"
}

"Mass Pos. (Max-Abs V) UMU"
{
   uFull
   {
        statusGood >= 0.0
        statusFair >= 5.0
        statusBad  >= 10.0
   }
   helpString = "Absolute Maximum Voltage for the Mass Position of the specified channel"
}
"Mass Pos. (Max-Abs V) UMV"
{
   uFull
   {
        statusGood >= 0.0
        statusFair >= 5.0
        statusBad  >= 10.0
   }
   helpString = "Absolute Maximum Voltage for the Mass Position of the specified channel"
}
"Mass Pos. (Max-Abs V) UMW"
{
   uFull
   {
        statusGood >= 0.0
        statusFair >= 5.0
        statusBad  >= 10.0
   }
   helpString = "Absolute Maximum Voltage for the Mass Position of the specified channel"
}


// the following is Data Latency of a given channel.  Change the channel
// name to any channel being monitored
"Secs of Data Latency HLZ"
{
   uFull
   {
        statusGood >= -2
        statusFair >= 120
        statusBad  >= 3600
   }
   uEval
   {
        statusGood >= -2
        statusFair >= 120
        statusBad  >= 3600
   }

   helpString = "Seconds of Delay between receipt of a packet (time of dlogagent Poll) and the end time of the packet == Data Latency for
 the channel specified."
}
"Secs of Data Latency HL4"
{
   uFull
   {
        statusGood >= -2
        statusFair >= 120
        statusBad  >= 3600
   }
   uEval

   {
        statusGood >= -2
        statusFair >= 120
        statusBad  >= 3600
   }

   helpString = "Seconds of Delay between receipt of a packet (time of dlogagent Poll) and the end time of the packet == Data Latency for
 the channel specified."
}
"Secs of Data Latency HL1"
{
   uFull
   {
        statusGood >= -2
        statusFair >= 120
        statusBad  >= 3600
   }
   uEval
   {
        statusGood >= -2
        statusFair >= 120
        statusBad  >= 3600
   }

   helpString = "Seconds of Delay between receipt of a packet (time of dlogagent Poll) and the end time of the packet == Data Latency for
 the channel specified."

}
"Secs of Data Latency HHZ"
{
   uFull
   {
        statusGood >= -2
        statusFair >= 120
        statusBad  >= 3600
   }
   uEval
   {
        statusGood >= -2
        statusFair >= 120
        statusBad  >= 3600
   }

   helpString = "Seconds of Delay between receipt of a packet (time of dlogagent Poll) and the end time of the packet == Data Latency for
 the channel specified."
}
////////////////////////////////////////////

"Average Clock Quality HHZ"
{
   uFull
   {

   {
     statusBad  >= 0.0
     statusFair >= 20.0
     statusGood >= 40.0
   }
   uEval
   {
     statusBad  >= 0.0
     statusFair >= 20.0
     statusGood >= 40.0
   }
   helpString="Average Clock Quality from Blockette 1001 of the last 2 packets from the datalog files for the channel specified. CRITERIA
: 0-20 BAD, 20-40 FAIR, >40 GOOD"
}

// this is the total percentage of all packets that are sequence errors.
"% Seq Err Since Boot"
{
   uFull
   {
     statusGood >= 0.0
     statusFair >= 5.0
     statusBad  >= 15.0
   }
   uEval
   {
     statusGood >= 0.0
     statusFair >= 5.0
     statusBad  >= 15.0
   }
   helpString = "This is the total percentage of all packets that are sequence errors since this station was attached to comserv. Sequenc
e Errors/ Total Packets Received * 100.0"
}

"% Seq Err Since Last Poll"
{
   uFull
   {
     statusGood >= 0.0
     statusFair >= 5.0
     statusBad  >= 15.0
   }
   uEval
   {
     statusGood >= 0.0
     statusFair >= 5.0
     statusBad  >= 15.0
   }
   uOff
   {
     statusGood >= 0.0
   }
   helpString = "http://iron.gps.caltech.edu/~isti/csagent.html"
   helpString = "http://iron.gps.caltech.edu/~isti/csagent.html"
}
// - a test of help for an unused DP
"Time of this CS Poll"
{
   uFull
   {
     statusGood >= 0
   }
   uEval
   {
     statusGood >= 0
     statusFair >= 5
   }
   uOff
   {
     statusGood >= 0
   }
   helpString = "This is the time when the COMSERV (CS) agent last polled the comerv memory area for this station. The time is from the c
sagent."
}

Station Templates Section

The remaining sections in the ruleset.ini file are the the station template definitions, which define station-template-names that are referenced in the station-information configuration file described below. Any section name that appears between square brackets [], other than [Usages], [Statuses], or [Criterias], will be considered a station-template-name beginning a new station section.  Note that the station-template-name "DefaultRuleSet" may be used with dynamically-created stations; see below for more information.

Within a station-template definition section are groups of criteria-block references, each of which contains a name, an open bracket {, a number of statements, and a close bracket }. The name is one of the "internal" usage-tag-names defined earlier in the file. Between the brackets {}, each statement appears in the following manner: 

paramname.blockname
where "paramname" is the name of the dynamic parameter defined in the [Criterias] section, and "blockname" is a reference to one of the criteria-blocks defined for that dynamic parameter. Thus, a user may specify different criteria depending upon the usage level of a given station or type of station.

An example station-template section follows: 

//Station Template Definitions:

////////////////////////////////////////////
[BasicAnalogRuleSet]

usageFull
{
   "% Seq Err Since Last Poll.uFull"
   "Secs Since Last Good Packet.uAnalog"
}

usageEval
{
   "% Seq Err Since Last Poll.uEval"
   "Secs Since Last Good Packet.uAnalog"
}

usageOff
{
   "% Seq Err Since Last Poll.uOff"
   "Secs Since Last Good Packet.uOff"
}
////////////////////////////////////////////
[BasicQuanterraRuleSet]

usageFull
{
   "% Seq Err Since Last Poll.uFull"
   "% Seq Err Since Boot.uFull"
   "Secs Since Last Good Packet.uFull"
   "Average Clock Quality HHZ.uFull"
   "Mass Pos. (Max-Abs V) UMZ.uFull"
   "Mass Pos. (Max-Abs V) UMN.uFull"
   "Mass Pos. (Max-Abs V) UME.uFull"
   "Mass Pos. (Max-Abs V) UMU.uFull"
   "Mass Pos. (Max-Abs V) UMV.uFull"
   "Mass Pos. (Max-Abs V) UMW.uFull"
   "Secs of Data Latency HHZ.uFull"
   "Secs of Data Latency HLZ.uFull"
}

usageEval
{
   "% Seq Err Since Boot.uFull"
   "% Seq Err Since Last Poll.uEval"
   "Secs Since Last Good Packet.uEval"
   "Average Clock Quality HHZ.uFull"
   "Mass Pos. (Max-Abs V) UMZ.uFull"
   "Mass Pos. (Max-Abs V) UMN.uFull"
   "Mass Pos. (Max-Abs V) UME.uFull"
   "Mass Pos. (Max-Abs V) UMU.uFull"
   "Mass Pos. (Max-Abs V) UMV.uFull"
   "Mass Pos. (Max-Abs V) UMW.uFull"
   "Secs of Data Latency HHZ.uFull"
   "Secs of Data Latency HLZ.uFull"
}

usageOff
{
   "% Seq Err Since Last Poll.uOff"
   "Secs Since Last Good Packet.uOff"
}
Examine a complete ruleset.ini file that contains all four of the above sections to see how it all fits together. The next section uses the station template definitions to tie a ruleset to a given station.

[Back to Top]

NSI stations_info.ini file:

The 'stations_info.ini' is a text file that defines a set of stations that the NSI server will process. Each section of the file begins with a network code, followed by a dash, followed by a short name for the station, with everything enclosed in square brackets (e.g., [CI-AGA]). All values following the station name are NSI-server-defined values for a given station and will be provided to the GUI client. There are two reserved values: 
        helpString = "Station Help URL or text"
        ruleSet = "StationTemplateName"
where 'helpString' is a URL that will be provided to the GUI if the end-user requests help for a particular station, and 'ruleSet' is the name of a station-template definition in the 'ruleset.ini' file. Any other values for a station that you wish to present to the end-user may be provided in this file. We recommend that you put "almost never changing" values in this file, like the lat/lon and station name here. There are referred to as the "configuration parameters" for a station. Any string-based values must be enclosed in quotes. The other mechanism for providing parametric data from a station is via the collection agents.

Dynamically-created stations: It is also possible for stations with names not listed in the 'stations_info.ini' file to be "dynamically-created" when their parameters first arrive from a collection agent. The collection agents for these stations may specify which station-template definition the stations use via a static parameter called "ruleSet".  If no "ruleSet" parameter is present then these stations will use the "DefaultRuleSet" station-template definition (if present).

An example 'station_info.ini' file with data for two stations is provided below: 

//SeisNetWatch Stations File
//
// Comments begin with // or # or appear within /* */


//Station Definitions:

[CI-ABL]
longName = "MOUNT ABEL"
ruleSet = "BasicAnalogRuleSet"
group = "Analog"
group = "Magma"

locationDescription = "MOUNT ABEL"
stationLatitude = 34.8484
stationLongitude = -119.2250
stationElevation = 1975.00
communicationsType = "Analog Microwave"
instrumentType = "L4C Short Period"
helpString = "http://terra10.gps.caltech.edu/dstatus.html"

[CI-AGA]
longName = "Agave Hill"
ruleSet = "BasicQuanterraRuleSet"
group = "Digital"
group = "FrameRelay"
locationDescription = "Agave Hill"
stationLatitude = 33.6384
stationLongitude = -116.4011
stationElevation = 781.00
communicationsType = "UDP/IP"
instrumentType = "Broadband Velocity and Episensor FBA"
helpString = "http://terra10.gps.caltech.edu/dstatus.html"


A complete stations_info.ini file for the TriNet network is provided here as an example.

[Back to Top]

NSI Startup:

The following is an example of an NSI server startup command:

java -Xms80m -Xmx100m -jar ../jars/isti.snwserver.jar -c ../conf/NSI_sim.conf

The pathname to the NSI configuration file should be provided after the "-c" parameter.  The Java archive file 'isti.snwserver.jar' provides the set of classes needed for the NSI server.  The parameters "-Xms80m" and "-Xmx100m" configure a larger memory heap for the NSI server, which can be needed when many station parameter history values are stored.

[Back to Top]

3.0 Control Agent (CTA) Configuration:

The control agent is used to change the usage level of a given station. It changes the usage level by running a control-script or control-program that will actually perform the usage level change (start or stop various comserv processes in the case of TriNet). Thus, the control agent acts as a program controller and does not actually know anything about what it is controlling. The control agent has 3 configuration files that tell it what its operational parameters are, where the event channels are, and what control scripts to use for specific stations. This section details the configuration files, their layout, how the control-script should be written, and how the control agent should be started.

[Back to Top]

Control agent file layout:

The control agent is written in java and uses many of the same configuration constructs that the NSI server does, and so it may be helpful to review the layout of files for the NSI above. The top level directory is known as the 'baseDir' and should contain a 'log' and 'conf' directory beneath it. Inside the 'conf' directory should go the 'orb.config', 'control.ini', and 'CTA.conf' files. The log directory will contain the 'CTA.log' file which logs all requests and actions.

[Back to Top]

Control agent 'orb.config' file:

The control agent needs to use three event channels to communicate with the NSI and these are found via the 'orb.config' file. The orb.config file is the same one built for the NSI server and is described above.

[Back to Top]

Control agent configuration file:

The 'CTA.conf' file is a text file which specifies all of the variables that the control agent uses at startup to find its initialization files ('orb.config', 'control.ini') and other configurable parameters. The most important parameters of the 'CTA.conf' for the sake of configuration are: 'baseDir', 'orbConfig', and 'controlFileName'.

The 'baseDir' parameter points to the root of the 'conf' and 'log' directories. If a 'baseDir' value is not provided, it defaults to '/usr/local/trinetwatch'. The 'controlFileName' points to the 'control.ini' file found in the 'conf' directory. The 'orb.config' filename can also be specified inside the 'CTA.conf' and it too must reside in the 'conf' directory. A more detailed description of the 'control.ini' file and the command line options to the control agent can be found in the control agent java doc.

An example 'CTA.conf' file is provided below: 

## This is an example configuration file for the Control Agent.
##
##

# In baseDir there will be the directories conf and log.
baseDir = "/home/isti/CTA/"

# The name of the gloabal CTA log file.  Default location:
# [baseDir]/log/CTA.log
globalLogFileName = "CTA.log"

# The desired level of message information.  Choices include: NO_MSGS, INFO,
# WARNING, ERROR, DEBUG, and ALL_MSGS.  The default is ERROR for both the 
# logfile and console.
logfileLogLevel = "DEBUG"
consoleLogLevel = "WARNING"

# The name of the file that holds the station control information.  Default
# filename and location:  "[baseDir]/conf/control.ini".
controlFileName = "control.ini"

# This is the name of the orb configuration file.  It is needed so that event 
# channels will work correctly.  Default name and location:
# [baseDir]/conf/orb.config
orbConfig = "orb.config_hotspot"

# The name of this Control Agent.  Each control agent must should have a 
# different name.
ctaName = "CTA-TestAgent-Hotspot1"

# Daemon mode.  
daemonMode = true
[Back to Top]

Control agent 'control.ini' file:

The control agent uses the 'control.ini' text file at startup to determine the stations it will control and the control-scripts needed to control the stations. The 'control.ini' file uses directives (keywords in square braces, e.g., [Usages]) to signify different control-blocks. Within a control-block, the Variable=Value format is used to assign values to configuration parameters. There are three control blocks needed for each 'control.ini' file: [USAGES], [CONTROL], and [STATIONS].

The [USAGES] control-block has only one parameter known as "usages" and its value is a comma-separated list of the usage numbers that are possible. These are the same numbers used in the ruleset.ini of the NSI server. 

[USAGES]
usages=1,2,3
The [CONTROL] control-block is used to specify types of control operations that are performed on stations. There can be more than one set of scripts used to control different sets of stations and thus a "type" parameter is used to distinguish between sets. The control-block for the control operations takes on the following format: 
[CONTROL]
type=type_designator
usage=1,path_to_script,timeout_in_seconds
...
usage=n,path_to_script,timeout_in_seconds
where 'type_designator' defines the set that follows and 'usage=' defines the set of scripts and timeouts that should be associated with this 'type_designator'. There can be any number of 'type=' items followed by 'n' 'usage= descriptors'. The values for the "usage" parameter are the usage level number, the path to the script that will perform the change to that usage level, and the maximum timeout that it will take to make the change to that usage level.

The [STATIONS] control-block matches up stations with a control-type listed in the [CONTROL] section. The first argument to the STATIONS control-block is the "control" parameter which points to a control type found in the [CONTROL] section and the "stations" argument which follows lists the stations which will use this control type. The stations must be given in a comma-separated list as follows: 

[STATIONS]
type=quanterra_control
station=CI-AGA,CI-SNCC,CI-SRN
An example control.ini file is shown below: 
# a comment

[USAGES]
numbers=1,2,3

[CONTROL]
type=generic_comserv_station_control
# The fields for the usage are:
# usage=usage_level,path-of-script,completion_timeout (secs)
usage=1,/home/isti/CTA/bin/usage_control.sh,3600
usage=2,/home/isti/CTA/bin/usage_control.sh,7200
usage=3,/home/isti/CTA/bin/usage_control.sh,7200

[STATIONS]
control=generic_comserv_station_control
stations=CI-PAS
[Back to Top]

Control agent control-script example:

The control agent control script or program is used to actually perform the usage level change. In the case of the TriNet network, the usage level corresponds to a set of comserv processes. Thus, a control-script in this case will start and stop given processes depending upon the desired usage level. The arguments to the control script are the networkCode-stationName and the usage level number. The example control script, provided with this documentation, performs the following steps:
  1. strip off the network code from the first argument
  2. find the station.ini file for the station from the /etc/stations.ini file
  3. save a copy of the original station.ini for archival purposes
  4. terminate all the comserv processes using netmon
  5. change the station.ini to reflect the new usage level
  6. restart all the comserv processes (also using netmon).
[Back to Top]

Control agent Startup Script:

The control agent is a Java program and is fairly easy to run if the CLASSPATH has been configured properly. The CLASSPATH must contain the ORBACUS .jar files and a path to the top level directory of the java classes used by the agent. We provide an example environmental setup file which we have created to help start the control agent here. The control agent should be started at boot time and must be restarted if the host on which the event channels reside should reboot (i.e., the event channels disappear).

Provided that the CLASSPATH and path are correctly configured, the control agent can be started simply with this command-line: 

java com.isti.trinetwatch.controlAgent.ControlAgent -c CTA.conf
[Back to Top]

4.0 SeisNetWatch GUI client configuration:

The SeisNetWatch GUI client may be run from a web page (as an applet) or as an application from the command line. The most usual mode will be as an applet from a secure web page.

To run the GUI client as an application, a command like the following one is used:
       java -jar application.jar
The archive file "application.jar" must be available.  If the parameter settings file "Client.ini" is present then it will be used.  The path to a CORBA object reference file (as a local pathname or as a URL address) may be given as a parameter.

The remainder of this section describes how to run the GUI client as an applet. To run in this mode, it must be lauched from an HTML document viewed by a browser. The browser must have a Java version 1.22 (or later) plugin installed or have equivalent browser support. The document must have access to the 'client.jar' file, and the applet must have access to a CORBA IOR file (usually named 'gui_acceptor_ior.ref') created by an NSI server. This section describes the setup of each of these files and provides examples.

[Back to Top]

GUI client HTML document file:

The GUI client's HTML document file contains the code used to launch the applet, the applet parameters used to control the displayed size of the program; and can also contain GUI client parameter settings. All of the GUI client parameters are described in detail in the GUI help section on applet parameters. A basic HTML document for launching the applet could contain the following code: 
<HTML>
<TITLE> SeisNetWatch Applet</TITLE>
<APPLET code="com.isti.trinetwatch.gui.Client.class" archive="client.jar"
        width="800" height="550">
    <param name="java_code" value="com.isti.trinetwatch.gui.Client.class">
    <param name="java_archive" value="client.jar">
    <param name="appletMode" value="Observe">
</APPLET>
</HTML>
In this example, the 'client.jar' and the CORBA IOR file must be located in the same directory as this HTML document. The 'width' and 'height' parameters govern the size of the applet as viewed in the browser. The parameter may be set to larger values to enlarge the displayed size of the applet. They may also be set the value "100%", which will size the applet to fill the entire browser window.

The 'appletMode' parameter governs one of two modes the GUI will start in, "Control" or "Observe". If "Control" mode is selected, then any user of the GUI may control a usage level from the Station Detail tab of the GUI.

This example HTML document will work in browsers that have native support for Java version 1.22 or later.  However, most current browsers do not have this level of native support, and so a Java plugin must be used to run the applet. The code to do this can be generated the by 'HtmlConverter' application from Sun, and can also found in several example files in the SeisNetWatch distribution.

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.

[Back to Top]

GUI client IOR file:

The GUI client communicates with the NSI using CORBA objects. In order to get the GUI client started, it needs to first obtain a reference to its initial CORBA object which the NSI serves up. This object is called the GUIAcceptorRefFile in the SeisNetWatch system and contains a unqiue identifier known as an Internet Object Reference or IOR for short. The NSI creates this IOR in a file as specified in the NSI.conf configuration file and its default filename is gui_acceptor_ior.ref. The applet will usually look for this filename in the directory where its HTML document is located. If the user wishes to place it elsewhere for security purposes, they can point to it with the applet parameter named "GUIAcceptorRefFile".

[Back to Top]

GUI client applet.jar:

The GUI client Java classes are provided as a self contained archive file known as a JAR file. The SeisNetWatch applet JAR file is named 'client.jar' and it should be located in the same directory as the HTML document file that refers to it.

[Back to Top]

Authors

The SeisNetWatch system was written by Eric Thomas, Jamey Linder, and Paul Friberg with oversight provided by Sidney Hellman and feedback from Ilya Dricker. Philip Crotwell wrote the initial eventdemo proof of concept software in Java and C++. We are ISTI.com.

Copyright 2001, Instrumental Software Technologies, Inc.


The ISTI home page

[Back to Top]