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. If you are not a academic institution and wish to use this software, you must purchase a license from ISTI.com.
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.
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" ## If "true" regular expressions can be used for criteria useCriteriaRegExFlag = "true" ## The name of the Unix time stamp parameter for dynamic parameters. If not
## specified or if set to an empty string then the current time will be used.
timeStampParamName = "SNW_SOH_TIME_STAMP" ## The percentage of stations to be the same for same status subsets. sameStatusPercent = "75"
The 'NSI.conf' file parameters are described in more detail in the
server
documentation.
[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.
//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.
archiveOverrideFlag = "Boolean"
helpString = "text"where "Boolean" is "true" to always archive or "false" to never archive and "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 one the following forms:
statusname >= ###or
statusname = "\regex\"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:
////////////////////////////////////////////////////////////// //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" } // - 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." }
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.blocknamewhere "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.
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.
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.
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.
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]
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,3The [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_secondswhere '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-SRNAn 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]
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]
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.4 (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.
<HTML> <TITLE> SeisNetWatch Applet</TITLE> <APPLET code="com.isti.trinetwatch.gui.Client.class" archive="client.jar" width="900" 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.4 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.
Copyright 2012, Instrumental Software Technologies, Inc.