ewagent (v0.07) Configuration File Commands

(last revised 26 June 2001)
Page Index:
1. Example configuration file
2. Functional command listing
3. Alphabetic command listing & description
4. Descriptor file example

On startup, ewagent reads the configuration file named on the command line. The ewagent feeds parametric data about trace_buf packets it observes in the specfied wave_ring to a SeisNetWatch NSI server.

As always, the configuraton file contains comments:

#  marks the line as a comment (example: # This is a comment).
Command names may be typed in the control file exactly as shown in this document (case of the command is irrelevant).

1. EXAMPLE CONFIGURATION FILE

# This is the ewagent.d that accompanies the ewagent for SeisNetWatch.
# SeisNetWatch is an open source product created by ISTI (all rights reserved).
# SeisNetWatch may be used freely by any Academic Institution or the USGS.
# For more information on this product contact us.

        # Earthworm setup details
                 ModuleName     MOD_EWAGENT
                 LoggingLevel   1       # 0 for off, 1 for on
                 RingName       WAVE_RING
                 PollDuration   5       # seconds to poll the wave ring for
                 PollInterval   360     # seconds to sleep between polls
                 UseNumericIPs  1       # 1 for CORBRA BOA to use numeric IPs
                                        # instead of host names (needed if
                                        # local host name is not in DNS)

        # agent specific info
        # agent name should be unique (no whitespace for any of the next 3 values!)
                 AgentName      TestAgentEW1
                 Region         NewYork
                 Installation   ISTI
        # Usage Level is needed if not running a csagent...almost
        # every installation should have this set to Full which for
        # the initial setup is 4
                UsageLevel 4

        # The CORBA event channels used for the NSI
        # these should point to the host where the NSI is running
StaticGetEventChannel iiop://terra-bytes.com:10011/DefaultEventChannel
DynamicEventChannel iiop://terra-bytes.com:10012/DefaultEventChannel
StaticEventChannel iiop://terra-bytes.com:10013/DefaultEventChannel

        # the following are only used for debugging
                 DebugLogDir            /home/rtem/tnw/log      # log directory
                 DebugMode              0       # 0=off, 1=stderr, 2=file
                 DebugLevel             0       # 1-3 (3 most verbose)

2. FUNCTIONAL COMMAND LISTING

Below are the configure commands recognized by ewagent, grouped by the function they influence. Most of the commands are required. Only UsageLevel, Debug___ and DPTimeout are optional. 
         Earthworm system setup:
                ModuleName      required
                RingName        required
                LoggingLevel    required
                PollDuration    required
                PollInterval    required
                AgentName       required
                Region          required
                Installation    required
        
         SeisNetWatch Communications:
                StaticGetEventChannel           optional
                StaticEventChannel              optional
                DynamicEventChannel             optional
                UsageLevel                      optional
                UseNumericIPs                   optional

         SeisNetWatch Debugging:
                DebugLogDir             optional
                DebugLevel              optional
                DebugMode               optional
                DPTimeout               optional

3. COMMAND LISTING & DESCRIPTION

In the following section, all configuration file commands are listed in alphabetical order. Listed along with the command (bold-type) are its arguments (in red), the name of the subroutine that processes the command, and the function within the module that the command influences. A detailed description of the command and is also given. Default values and example commands are listed after each command description.
command arg1                            processed by            function

AgentName name                                          Earthworm setup
This is the unique name for this agent. No other agents in system should share this name.

Default:  none, required option                         
USGS:   AgentName       Caltech_k2ew_monitor

DebugLogDir directory_name                                              Earthworm setup
This is used only for ewagent debugging and is separate from Earthworm logging. It should only be used to debug the ewagent process. If the DebugMode is set to 2, then the debug log is built using the AgentName.log.

Default:  none, optional
Example:   DebugLogDir  /some/directory/log

DebugLevel level                                                Earthworm setup
This parameter sets the verbosity of ewagent debugging messages. This is used only for ewagent debugging and is separate from Earthworm logging. This is the verbosity level of logging from 0 to 3, with 3 being the most verbose.

Default:  0, optional
Example:   DebugLevel   3

DebugMode mode                                          Earthworm setup
This parameter sets output of ewagent debugging messages. This is used only for ewagent debugging and is separate from Earthworm logging. A value of 0 turns off ewagent debugging, a value of 1 spews the messages to stderr, and a value of 2 sends the messages to a log file named AgentName.log

Default:  0, optional
Example:   DebugMode    0

DPTimeout Useconds                                              DP thread
This parameter sets time delay in micro seconds between each DP message being sent. The default value is 500 and this should not be tampered with unless you have experience with the event channel mechanism of CORBA.

Default:  0, optional
Example:   DebugMode    0

DynamicEventChannel iiop_string                         DP thread
This is the IIOP specification for the CORBA event channel used to send dynamic parameter responses to the SeisNetWatch NSI server. This should be set to the same value as the one configured for the NSI server (see the value for "DynAgentEventService" in the 'orb.config' file in the NSI server's 'conf' directory).

Default:  none, optional
Example:   DynamicEventChannel iiop://nsi.gps.caltech.edu:10022/DefaultEventChannel

Installation name                                               Earthworm setup
This is reported by the ewagent and is simply informative to the end user as to where this agent is reporting from. Installation is defined as the group running the ewagent.

Default:  none, required option                         
USGS:   Installation    CalTech

LoggingLevel switch                             Earthworm Setup
Sets the on-off switch for writing a log file to disk. If switch is 0, no log file will be written. If switch is 1, ewagent will write a daily log file(s) called ewagentxx.log_yymmdd where xx is ewagent's module id (set with "ModuleName" command) and yymmdd is the current UTC date (ex: 960123) on the system clock. The file(s) will be written in the EW_LOG directory (environment variable).

Default:  none

ModuleName mod_id                       Earthworm setup
Sets the module id for labeling all outgoing messages. mod_id is a character string (valid strings are listed in 'earthworm.d') that relates (in 'earthworm.d') to a unique single-byte number.

Default:  none                          
USGS:   ModuleName MOD_EWAGENT

PollDuration seconds                    main                    DP ewagent Thread
This defines how long the ewagent polls the WaveRing for trace_buf packets. seconds is the duration in seconds to poll.

Default:  none
Example: 
        PollDuration 10

PollInterval seconds                    PollInterval            Earthworm setup
This command is used to define how long the ewagent waits between polls of the WaveRing for trace_buf packets. seconds is the interval in seconds to sleep between each poll.

Region name                                             Earthworm setup
This is reported by the ewagent and is simply informative to the end user as to where this agent is reporting from. Region is intended to define a number of installations.

Default:  none, required option                         
USGS:   Region  SouthernCalif

RingName ring                           Earthworm setup
This is the ring into which the waveforms and messages are sent.

Default:  none, required option                         
USGS:   RingName WAVE_RING

StaticEventChannel iiop_string                          DP thread
This is the IIOP specification for the CORBA event channel used to send static parameter responses to the SeisNetWatch NSI server. This should be set to the same value as the one configured for the NSI server (see the value for "StatAgentEventService" in the 'orb.config' file in the NSI server's 'conf' directory).
This event channel is not currently used by the ewagent.

Default:  none, optional
Example:   StaticEventChannel iiop://nsi.gps.caltech.edu:10023/DefaultEventChannel

StaticGetEventChannel iiop_string                               DP thread
This is the IIOP specification for the CORBA event channel used to listen for static parameter queries from the SeisNetWatch NSI server. This should be set to the same value as the one configured for the NSI server (see the value for "CaRequestEventService" in the 'orb.config' file in the NSI server's 'conf' directory).

Default:  none, optional
Example:   StaticGetEventChannel iiop://nsi.gps.caltech.edu:10021/DefaultEventChannel

UsageLevel level                                Earthworm setup
SeisNetWatch expects at least one of its agents to establish the "usage level" for any given station, which can be used to indicate the mode of the station's acquisition software.  This NSI definable parameter is a numeric value. For the USGS installation, set the UsageLevel to 1. For the other SeisNetWatch installations (where the 'csagent' is being used), this command should be omitted.

Default:  none, optional
USGS:   UsageLevel 1

UseNumericIPs switch                             Earthworm setup
When 'UseNumericIPs' is set to 1, the ORBacus CORBA implementation is prevented from attempting to use the canonical name of the local host when connecting to the event channels.  On machines whose names are not resolvable via DNS, having 'UseNumericIPs' set to 1 prevents a 'COMM_FAILURE' exception error from occurring.

Default:  1
USGS:   UseNumericIPs 1

4. DESCRIPTOR FILE EXAMPLE

Here is a copy of the 'ewagent.desc' file as implemented.

NOTE that the ewagent sends a heartbeat at the beginning and end of each poll. That is, it sends a heartbeat when it wakes up from its sleep period (defined by PollInterval) and before it goes back to sleep (or PollDuration seconds after the first heartbeat). This means you must carefully calculate the .desc heartbeat interval for the statmgr process based on the two polling times defined.

modName  ewagent
modId    MOD_EWAGENT
instId   INST_MENLO

restartMe       # restart this sucker as it is critical to data collection
#
#
#    Heartbeat Specification.  If the status manager does not receive
#    a heartbeat message every  seconds from this module, an
#    error will be reported (client module dead).   is the maximum
#    number of pager messages that will be reported and  is the
#    maximum number of email messages that will be reported.  If the
#    page or mail limit is exceeded, no further errors will be reported
#    until the status manager is restarted.
#
tsec: 20  page: 0  mail: 99
Module Index | ewagent Overview


For more information please contact us.