Instrumental Software Technologies, Inc.

SeisNetWatch Agents Configuration Map

Last Updated June 25, 2012

1.0 Introduction:

SeisNetWatch is designed as a control and observation tool for the TriNet seismic network. SeisNetWatch is the tool used by the Network operators to monitor the state of health of the TriNet network and to control the data acquisition software. This document is a configuration roadmap to all of the files that the SeisNetWatch system needs in order to run. This is not an installation manual, please refer to the INSTALL document for these details. The specifics of each config file are explained in more detail in the documentation for each component and 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 all 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 and the NSI server is a Java Application. The Collection and Control Agents may be written in C++ or Java. The collection agents provided to CalTech are written in C++ and monitor data from comserv shared memory and datalog files. 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 contact us for licensing terms.

2.0 COMSERV (csagent) Collection Agent:

The comserv collection agent, csagent, collects static and dynamic parameters from the comserv station.ini files and the comserv shared memory area, respectively. The csagent requires two files in order to run: a collection.ini file which specifies run parameters and which stations to operate on, and a orb.config file which points to the event channels used to communicate with the NSI. This section briefly discusses the two configuration files. In addition, if static parameters from the station.ini file for each station are to be sent to the NSI, the station.ini file must be edited to reflect this. The startup of the csagent should be done from a script or from the /etc/inittab file at boot time. The startup of the csagent is also discussed in this section.

[Back to Top]

csagent File Layout:

The csagent makes no requirements on where the files should reside, however if multiple collection agents are used, the collection.ini files for each agent should be distinctly named. Furthermore, it would be helpful to collect all of the .ini files in one directory. If logging of the csagent actions is to be performed, the .log file should also be stored in a single directory. So, like the NSI, a conf and log directory could (but do not have to be) created to help in organizing the information.

[Back to Top]

csagent orb.config file:

The csagent needs to know about 3 event channels so that it can communicate with the NSI. The same orb.config file used by the NSI should be distributed to the host running the csagent. Refer to the NSI orb.config file above for more details on this file.

[Back to Top]

csagent collection.ini file:

The collection.ini is a text file which describes how the csagent will run. The file can be named anything since it is passed on the command line to csagent as an argument. An example collection.ini file is provided here.

The collection.ini file for the csagent is described in detail in the csagent manual page and only some of the important configuration settings are described here.

There are three sections to the collection.ini file, [TIMEOUTS], [USAGES], and [STATIONS]. Timeouts for data collection polling are specified in the TIMEOUTS section. The most important of the timeouts is the DPGatherWait which is the number of seconds to wait between polling the comserv shared memory area. 

[TIMEOUTS]
* SPTimeout - how many microsecs to wait before each SP_MSG is spewed
SPTimeout=1000
*
* DPTimeout - how many microsecs to wait before each DP_MSG is spewed
DPTimeout=1000
*
* DPFailoverTimeout - how many SECS to wait before spewing DP messages
DPFailoverTimeout=30
*
* DPGatherWait - how many SECS to wait before gathering all DP messages
DPGatherWait=30
The [USAGES] section should map usage level number (as specified in the NSI ruleset.ini file) to a set of comserv processes. 
* the usage level mapping section (comlink translates to mserv or comserv)
[USAGES]
1=off
2=comlink,dlog
3=comlink,dlog,cwda
The [STATIONS] section is probably the most important section since it specifies which stations the csagent polls for parameters and the debug level. The "Stations" parameter is a comma separated list of the stations (without network codes) that the csagent will operate on. The "NetworkCode" parameter specifies the FDSN Network Code for the set of stations and is used by the NSI for displaying the station names. The "AgentName" parameter uniquely identifies this agent and all of its dynamic parameters and is mainly used for debugging purposes. If the DebugMode is set to 2 (store to a file), then the AgentName is used to create a AgentName.log file in the directory where the csagent is run. To specify another directory (recommended), the "DebugLogDir" should be set to this location. An example [STATIONS] section is shown below: 
* The following section contains Collection Agent details
[STATIONS]
*
* Stations tells which stations to operate on 
*               (Stations=*) means ALL stations specified in Init file
Stations=ABL,AGA,AGO,ALP,ALV,ARG,ARV,BAC,BAK,BAL,BAR,BAT
NetworkCode=CI

* Init - points to an initialization specific file.
Init=/etc/stations.ini

* AgentName - name of this agent
AgentName=TestCA1

##########################################################
* DebugMode - set to 0 for off, 1 to spew messages to stderr, 2 to file
DebugMode=2
* DebugLevel - set to the level of debug you want 0-3, higher == more verbose
*               0 = sys, 1 = run, 2 = init, 3 = spill your guts
DebugLevel=3

DebugLogDir=/home/isti/collection/log
[Back to Top]

csagent station.ini modifications:

The csagent uses the station.ini file of comserv to establish which static parameters to send to the NSI and which comserv clients should be running. The modifications to the station.ini are limited to a directive [CAStaticParams] which specifies the static values that should be sent to the NSI. Following the directive, the user may put in a 
statParamName="value"
where the "statParamName" is the name of the static parameter and the "value" is a numeric or string enclosed in quotes. If the statParamName is set to the reserved word getComservParams, a comma separated list of station.ini keywords is expected and each of these keywords respective values will be retrieved from the station.ini file. An example below shows the use of this for the station.ini file for AGO. 
[CAStaticParams]
getComservParams="mcastif,udpaddr,ipport"
LastUser="AGO station.ini edited by Paul F."
LastEdit="July 4, 2000 12:00 PM"
In this example, the getComservParams is used and indicates that three comserv parameters from the station.ini file should be sent: mcastif, updaddr, and ipport. In addition, there are two static parameters which indicate who edited the file and when. All of this information will be passed to the NSI and viewable in the GUI station detail tab for this station.

[Back to Top]

csagent Startup Script:

The csagent can be run from any directory and has only 2 command line arguments: the orb.config file and the collection.ini file. An example command line starting the csagent is shown below: 
csagent -ORBconfig orb.config collection.ini
Since the csagent is a dynamically linked executable program it requires access to some of the GNU C++ libraries (for Solaris, these are stored on the /usr/local/lib directory), and thus the LD_LIBRARY_PATH must be set to include the appropriate directory.

The order of starting of the csagent and NSI are irrelevant. The csagent will wait polling for the event channels to appear before it takes any action. However, if the host computer on which the NSI resides (and thus the event channels) dies, then the csagent will exit with a communications failure and needs to be automatically restarted. This can be done with a simple C shell script as described below: 

#! /bin/csh

cd /home/isti/csagent/conf

while (1)
        csagent -ORBconfig orb.config collection.ini
#       wait 60 seconds for the NSI host to reboot
        sleep 60
end
Alternatively, the csagent can be started and maintained in the init process and respawned as necessary. See the init manual page for details and create an /etc/inittab entry if you wish to use this respawning technique.

[Back to Top]

3.0 DLOG Agent (dlogagent) configuration:

The dlogagent polls the "active" files of the datalog comserv client for three parameters: mass position, clock quality, and data latency. It requires an orb.config and a collection.ini file to run. It also requires that some directives be placed in the station.ini file for each station that will be monitored. This section provides a description of the configuration files, the directives for the station.ini and a startup script suggestion. The manual page for the dlogagent should be referred to for more detail.

[Back to Top]

dlogagent file layout:

Like the csagent, the dlogagent does not require any file heirarchy to run. The dlogagent only requires the orb.config and collection.ini files be readable. To keep the configuration for the dlogagent organized, a conf directory, to hold the two config files, and a log directory, to hold optional logging files, could be created.

[Back to Top]

dlogagent orb.config file:

The dlogagent needs to know about only 1 event channel so that it can communicate dynamic parameters to the NSI. The same orb.config file used by the NSI should be distributed to the host running the dlogagent. Refer to the NSI orb.config file above for more details on this file.

[Back to Top]

dlogagent collection.ini file:

The dlogagent requires a text initialization file, known as the collection.ini file, to determine which stations it will operate on and what its configuration will be. The dlogagent collection.ini file is nearly identical to the collection.ini for the csagent. The only difference between the files is that the dlogagent does not provide static parameters and hence does not have some of the timeout values associated with these parameters. Please refer to the description of the collection.ini file for the csagent above for more details.

[Back to Top]

dlogagent station.ini modifications:

The dlogagent reads the station.ini for each station it is configured to operate on. It obtains from the station.ini a list of parameters and channels for those parameters which it will monitor for the particular station. Inside the station.ini the user may place a directive [CADynamicParams] which indicates that a list of dynamic parameters will follow. Following the directive, the user enters a dynamic parameter followed by a channel list in the following manner: 
DynamicParamName="chan1,chan2,chan3,..."
where DynamicParamName can be one of the following: DataLatencyChannels, ClockQualityChannels, or MassPositionChannels. The channel list must be quoted, comma separated (no whitespace), list of channels that should be monitored for the given dynamic parameter. An example from a station.ini file is shown below: 
[CADynamicParams]
DataLatencyChannels="BHZ,HHZ"
ClockQualityChannels="HHZ"
MassPositionChannels="UMZ,UME,UMN"
* end of the dynamic params section
[Back to Top]

dlogagent Startup Script:

The dlogagent can be run from any directory and has only 2 command line arguments: the orb.config file and the collection.ini file. An example command line starting the dlogagent is shown below: 
dlogagent -ORBconfig orb.config collection.ini
Since the dlogagent is a dynamically linked executable program it requires access to some of the GNU C++ libraries (for Solaris, these are stored on the /usr/local/lib directory), and thus the LD_LIBRARY_PATH must be set to include the appropriate directory.

The order of starting of the dlogagent and NSI are irrelevant. The dlogagent will wait polling for the event channels to appear before it takes any action. However, if the host computer on which the NSI resides (and thus the event channels) dies, then the dlogagent will exit with a communications failure and needs to be automatically restarted. This can be done with a simple C shell script as described below: 

#! /bin/csh

cd /home/isti/dlogagent/conf

while (1)
        dlogagent -ORBconfig orb.config collection.ini
#       wait 60 seconds for the NSI host to reboot
        sleep 60
end
Alternatively, the dlogagent can be started and maintained in the init process and respawned as necessary. See the init manual page for details and create an /etc/inittab entry if you wish to use this respawning technique.

[Back to Top]

Authors

The SeisNetWatch system was written by Eric Thomas, Kevin Frechette, 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 2012, Instrumental Software Technologies, Inc.


The ISTI home page

[Back to Top]