Earthworm Modules:
Wave_ServerV Configuration File

(last revised 7 July, 2008)
Page Index:
1. Functional command listing
2. Alphabetic command listing & description
3. Sample Configuration File

On startup, wave_serverV reads the configuration file named on the command line. Commands in this file set all the parameters used for configuring the Earthworm wave_serverV module. In the control file, lines may begin with a valid wave_serverV command (listed below) or with one of 2 special characters:

#  marks the line as a comment (example: # This is a comment).
@ allows control files to be nested; one control file can be accessed from another with the command "@" followed by a string representing the path name of the next control file (example: @model.d).
Command names must be typed in the control file exactly as shown in this document (upper/lower case matters!). Blank lines are also permitted in the control file.

1. FUNCTIONAL COMMAND LISTING

Below are the commands recognized by wave_serverV, grouped by the function they influence. Some of the commands are required, as noted. They may be specified in any order in the control file.

   Earthworm system setup:
                MyModuleId                required
                RingName                required
                LogFile                 required
                HeartBeatInt            required

        Wave Server Required Commands:
                ServerIpAdr
                ServerPort
                Tank
                GapThresh
                IndexUpdate
                TankStructUpdate
                InputQueueLen
                TankStructFile
                SocketTimeout

        Wave Server Optional Commands:
        	AbortOnSingleTankFailure
                ClientTimeout
                RedundantTankStructFiles
                RedundantIndexFiles
                TankStructFile2
                MaxMsgSize
                PleaseContinue
                ReCreateBadTanks
                SecondsBetweenQueueErrorReports
                MaxServerThreads
                QueueReportInterval
                Debug
                SocketDebug
                UsePacketSyncDb
                PacketSyncDbFile
                PurgePacketSyncDb

2. ALPHABETIC 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                                       function

AbortOnSingleTankFailure M

Set to 0 to have wave_server continue even if there is a fatal error on a tank during normal processing. If this flag is not set to 0, wave_server will die if any type of IO error occurs on any tank. If set to 1 wave_server will not exit unless there is a server wide error.

Default:  none
Example:  AbortOnSingleTankFailure 0

ClientTimeout M

Sets the timeout of M milliseconds for response from a client. If there are no idle server threads (set by MaxServerThreads), the server manager will disconnect clients and kill server threads that have not heard anything from their client in this period. Comment out or set to -1 if you don't want to kill threads of silent clients.

Default:  -1 (client timeout disabled)
Example:  ClientTimeout 60000

Debug n                             Earthworm Setup

Sets the wave_serverV debug level to n. Level zero gives no debugging output; level one turns on debugging. Due to the large number of transactions that a wave server typically handles, very large amounts of debugging output may be produced.

Default:  0 (no debugging)
Example:  Debug 1

GapThresh G

Sets the gap threshold to G sample intervals. Trace data packets are timestamped with a start time and a stop time, the times of the first and last samples in that packet, respectively. Thus, the expected gap between end time of one packet and the start time of the next packet is one sample interval. Some data sources, such as older digitizers, produce data with slightly larger or smaller intervals between them. The gap threshold is intended to provide a means of detecting missing packets, without falsely declaring a missing packet because of sloppy timestamps. The preferred value for this gap threshold is 1.5. Set larger values only if you have a sloppy data source. It is not clear how wave_serverV should handle intervals of much more than one sample interval between packets if these are not caused by missing packets.

Default:  none
Example:  GapThresh 1.5

HeartBeatInt nsec                             Earthworm Setup

Defines the number of seconds, nsec between TYPE_HEARTBEAT messages issued by wave_serverV.

Default:  none
Example:  HeartBeatInt 30

IndexUpdate U

Defines the interval in seconds U between which the index files are written to disk. Decreasing this number will keep the index file closer to the conditions in the tank file, but will increase disk activity. Each index file update involves opening the file, writing the new index, and closing the file. If RedundantIndexFiles are being used, then the update is alternated between the two index files for each tank.

Default:  none
Example:  IndexUpdate 10

InputQueueLen M

Sets the size of the input queue to M messages. Trace_buf messages are buffered in a queue when they are pulled off of an earthworm message ring. They are removed from the queue when the main thread is ready to process them. Depending on the CPU and disk speed of the machine you are using, this number should be about twice the number of tanks you are trying to serve. Slower machines may need larger queues.

Default:  none
Example:  InputQueueLen 200

LogFile 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 non-zero, wave_serverV will write daily log file(s) called nnnnnxx.log_yyyymmdd where nnnnn is the name of the configuration file (with the suffix `.d' removed), xx is wave_serverV's module id (set with MyModuleId command) and yyyymmdd is the current UTC date (ex: 19960123) on the system clock. The file(s) will be written in the EW_LOG directory (environment variable).

Default:  none
Example:  LogFile   1

MaxMsgSize S

Optional command to set the maximum trace_buf2 message size to S bytes. Normally, wave_serverV calculates the maximum expected message size from the record size values given in Tank commands. But if larger trace_buf2 messages are found on wave_serverV's transport ring, such as SCNL's destined for a different wave_serverV, their size must be set here. This is because wave_serverV must allocate a buffer for examining each trace_buf2 message it finds on the transport ring, and this command is the only way it knows how large to make that buffer. If trace_buf2 messages are found with a larger size than given here or in the Tank commands, wave_serverV will send an error message to statmgr. If in doubt, you can set this command to 4096, the largest trace_buf2 message allowed in earthworm.

Default:  same as largest record size in Tank commands
Example:  MaxMsgSize 1064

MaxServerThreads T

Sets the maximum number of server threads to T. One server thread is created for each client connected to the wave_serverV. The more server threads you allow, the more load will be placed on wave_serverV and the computer.

Default:  10
Example:  MaxServerThreads 12

MyModuleId mod_id                                  Earthworm setup

Sets the module id for labeling all outgoing heartbeat and error messages. mod_id is a character string (valid strings are listed in earthworm.d; maximum length is 29 characters) that relates to a unique single-byte number. In general, a different module ID is needed for each instance of wave_serverV.

Default:  none
Example:  MyModuleId MOD_WSV_1

PacketSyncDbFile name

Defines the filename of the database to use for asynchronous packet buffering. The argument name may contain path information in addition to the name of the file. This setting is only valid if UsePacketSyncDb is set to 1.

Default:  TB2PACKETS.SL3DB
Example:  PacketSyndDbFile "FOO.DB"

PleaseContinue X

Sets the PleaseContinue flag to X. If this flag is zero and wave_serverV has errors opening and reading its tank or index files, wave_serverV will exit. If it is set to any non-zero value, wave_serverV will continue after handling those tank file errors.

Default:  0 (does not continue after tank file errors)
Example:  PleaseContinue 1

PurgePacketSyncDb U

Defines whether wave_serverV should purge all asynchronous trace buffer packet data on startup. If the argument U = 1 then the packet data is deleted on startup. If it is 0 then packet data is not purged on startup. Note that packet data is purged periodically during the operation of wave_serverV if UsePacketSyncDb is set to 1.

Default:  0
Example:  PurgePacketSyncDb 1

QueueReportInterval R

Defines the number of seconds, R between queue reports. The queue report lists the high and low queue levels for the previous interval. These reports show up in the log file and on standard error output.

Default:  30
Example:  QueueReportInterval 300

ReCreateBadTanks X

Sets the ReCreateBadTanks flag to X. If this flag is set, then any tanks that were listed in the tank structure file and had errors will be recreated using the parameters in the structure file. Any tanks that were listed only in the config file and had errors will not be constructed. See Wave Server Startup in the overview file for more details. It is very unlikely that setting this flag will help you. Usually it will "recreate bad tanks".

Default:  0 (bad tanks are not recreated)
Example:  ReCreateBadTanks 1

RedundantIndexFiles X

Sets the RedundantIndexFiles flag to X. If this flag is set, then two index files will be created for each tank file. If not set, then only one index file is created for each tank file. The index file names are based on the tank file names with "-1.inx", and if two files, "-2.inx" appended. Only a single index file is actually open for all the tanks at any given instant. We recommend that you set this flag to 1.

Default:  0 (single index files for each tank)
Example:  RedundantIndexFiles 1

RedundantTankStructFiles X

Sets the RedundantTankStructFiles flag to X. If this flag is set then two tank structure files will be used. If this flag is zero, then only one tank structure file will be used. The first tank structure name is given with the TankStructFile command. If two tank structure files are to be used, then you must also specify the second structure file name with the TankStructFile2 command. Because of the importance of the tank structure file for restarting wave_serverV, it is strongly recommended that you use two tank structure files, by setting the RedundantTankStructFiles flag.

Default:  0 (single tank structure file)
Example:  RedundantTankStructFiles 1

RingName ring                                      Earthworm setup

Tells wave_serverV which shared memory region to use for input and output. ring is a character string (valid strings are listed in earthworm.d; maximum length is 19 characters) that relates to a unique number for the key to the shared memory region.

Default:  none
Example:  RingName WAVE_RING

SecondsBetweenQueueErrorReports Q                             Earthworm Setup

Defines the number of seconds, Q between error reports about the internal message queue. Normally when the message queue gets full, an error message would be generated for each new trace_buf2 message that was supposed to go in the queue. This could be many messages per second. To limit the number of error messages to a more reasonable frequency this parameter should be set to the desired interval. The error messages indicate the number of trace_buf2 messages that failed to enter the full queue during the last reporting interval. If you get queue full error messages very often, it means that wave_serverV, and probably your computer, is not keeping up with its assigned load.

Default:  60
Example:  SecondsBetweenQueueErrorReports 30

ServerIpAdr addr

Specifies the IP address, addr to which wave_serverV will listen for client connections. This must be the IP address of (one of) your computer's network interface(s), and it must be an numeric IP address, not a host or domain name.

Default:  none
Example:  ServerIpAdr 192.168.7.13

ServerPort nnn

Specifies the TCP port, nnn on which wave_serverV will listen for client connections. It must be a port number not used by any other service on the assigned IP address.

Default:  none
Example:  ServerPort 16021

SocketDebug D

Sets the socket debug level, D for earthworm's socket library functions. Level 0 turns debugging off, level one is full socket debug logging.

Default:  0 (no socket debug output)
Example:  SocketDebug 1

SocketTimeout m

Sets the socket timeout interval to m milliseconds. This is for calls sending responses back to the client. Values should be a few seconds, certainly less than one minute. If the timeout is exceeded, the client is disconnected and the socket is closed.

Default:  none
Example:  SocketTimeout 10000   # timeout of ten seconds

Tank station channel net loc recsize inst_id mod_id tanksize indexsize tankfile-name                             Required

Specifies the parameters for one wave_serverV tank. This command is the heart of wave_serverV configuration. Use one Tank for each tank to be managed by this wave server, up to a maximum of 512 tanks. Computer systems limit this to a smaller value: on Unix (Solaris), the limit is about 220, based on the stdio limit of 256 open files. On WindowsNT, the limit is about 200.

The wave trace data is selected for a Tank by the station, channel, net, and loc values (the SCNL); these names must match exactly the names found in the trace data.

The amount of space alloted for each wave trace (trace_buf2) packet in the tank file is given by recsize. This value, in bytes, must be at least as large as the largest trace_buf2 packet expected for this SCNL, and must be a multiple of 4. Trace_buf packets consist of a 64-byte header, plus the trace data samples in binary format (either 2 or 4 bytes per sample.) A handy tool for seeing the size of trace_buf2 packets is the earthworm utility sniffwave. If trace_buf2 messages for this SCNL are found to be larger than recsize, they will be skipped and and error message will be sent to statmgr.

To further specify which trace_buf2 packets are read by wave_serverV, you can set the inst_id and mod_id to specific values (found in earthworm_global.d in the params directory.) Trace_buf that have been produced at the earthworm installation with net_id and the module with mod_id will be selected; all others will not. Often it is more convenient to allow trace data from any installation; in that case, inst_id would be set to INST_WILDCARD. Likewise for the moduleId, using MOD_WILDCARD.

The tanksize parameter sets the size of the tank in millions of bytes (ten to the sixth power, not 2 to the 20th power!). To figure out how large to make your tank files, multiply these quantities together: recsize, number of trace packets per second for this SCNL, and required duration of the tank in seconds. Be sure to allow sufficient disk space for this and all the other tank files!

The size of the index file (or files if RedundantIndexFiles is set to 1) is specified as indexsize entries. Each index entry is about 20 bytes, not large. Each index entry records the start time, tank file location (offset) and endtime of a "chunk" of trace data. A new "chunk" of trace data is started whenever there is a gap larger than GapThresh sample intervals between the end time of one trace_buf2 packet and the start of the next one in the tank. So if you have lots of gaps in trace data for one SCNL (due to telemetry problems, for example) be sure to make the index files large enough. If wave_serverV runs out of index entry for an tank, it will send an error message to statmgr. Then it will overwrite the oldest index entry with new information. The result will be that the trace_data referenced by that just erased index entry will no longer be accessible from the tank file.

If you find that you need to increase the size of your index files, you can do so by changing indexsize and restarting wave_serverV. Do not remove the old index files; they will be extended with new, blank entries for later use.

If you have valuable old data in a tank file that has become inaccessible because of index file problems, it is possible to reconstruct the index file, using either wave_serverV or the utility inspect_tank. If you need assistance with this, ask for help from the earthworm mailing list or Earthworm Central. Naturally, your need will likely come in the heat of battle, so don't panic and delete files that might be useful.

The last parameter in the Tank command is the tankfile-name; this gives the full pathname for the tank file. We recommend that you make the tank name similar to the SCNL to aid in file manipulation.


Default:  none
Example:  Tank    SEA BHZ UW --  264   INST_UW    MOD_WILDCARD       10         100         /earthworm/run/tanks/SEA_BHZ.tnk

TankStructFile name                             Required

Specifies the name of the first tank structure file. This should be a full pathname, not a simple file name. This structure file name traditionally ends in "-1.str", but this is not required. The tank structure file contains configuration parameters for all existing tank files. It also contains the location in the tank file where new trace data is to be added. This data insertion point (a file offset) is updated in the tank structure file at the interval specified by TankStructUpdate.

Default:  none
Example:  TankStructFile j:\data\usgs\datafiles\p1000-1.str

TankStructFile2 name

Specifies the name of the second tank structure file. This command is required if RedundantTankStructFiles is set to 1; otherwise it is ignored. This should be a full pathname, not a simple file name. This structure file name traditionally ends in "-2.str", but this is not required.

Default:  none
Example:  TankStructFile2 j:\data\usgs\datafiles\p1000-2.str

TankStructUpdate U                             Required

Defines the number of seconds, U between tank structure file updates. The TANK structure is maintained in memory, and periodically written to disk. The TANK structure tracks the status of the all the tank files. Any data written to the tanks since the last time the TANK structure was written to disk is effectively lost if wave_serverV crashes. The larger the interval, the more tank data is potentially lost in a crash; the smaller the update interval the more disk I/O that is required for wave_server to operate. We recommend a structure file update interval of one second.

Default:  none
Example:  TankStructUpdate 1

UsePacketSyncDb U

Defines whether to buffer asynchronous trace buffer packets to a database and resynchronize them into the client streams. This feature may be turned on by specifing 1 for U. This feature is off by default. If specied the configuration parameters PacketSyncDbFile and PurgePacketSyncDb may be used to configure its behavior but are not required.

Default: 0
Example: UsePacketSyncDb 1


3. Sample Configuration File

#
#         Wave ServerV Configuration File
#
#	Note:  All directories defined in this configuration file must already
#		exit or WaveServerV will die.
#
MyModuleId    MOD_WAVESERVERV # wave_server's module id
RingName      WAVE_RING        # name of transport ring to get data from
LogFile       1                # 1=write log file to disk; 0=don't
                               # 2=write to module log but not stderr/stdout
HeartBeatInt  15               # seconds between heartbeats to statmgr
ServerIPAdr   192.168.1.5      # address of machine running wave_server: geops.geophys
ServerPort    16022            # port for receiving requests & sending waves
GapThresh     1.5              # threshhold for gap declaration
                               # (in sampling periods)

#

SocketTimeout 11000  # Timeout length in MILLISECONDS for socket calls
                     # This is for calls sending responses back to the
                     # client. Values should be a few seconds, certainly
                     # less than one minute.


ClientTimeout  60000 # Optional.  Not recommended feature but it does work.
                     # Timeout in MILLISECONDS for response from client.
                     # Threads that have not heard anything from their client
                     # in this period will exit.
                     # Comment out or set to -1 if you don't want to
                     # kill threads of silent clients.


# Each tank file has an associated in-memory index.  On re-start, the
# index image on disk must be updated to match the tank.  The more out
# of date the on-disk index is, the longer it takes to rebuild.  Rebuild
# times can be from milliseconds to minutes per tank, depending how large
# the tank is and how old the index is.
# Set IndexUpdate to the length in time in seconds between
# updates to disk.  The larger the update interval, the longer
# a crash recovery will take.  The smaller the update interval
# the more disk I/O that is required for wave_server to operate,
# and thus the slower it will operate, once it has reached I/O
# saturation.

IndexUpdate   10


# Similar to an Index, each tank has TANK structure that depicts the tank.
# The tank structure is maintained in memory, and periodically written to
# disk.  The TANK structure tracks the status of the tank.  Any data written
# to the tank since the last time the TANK structure was written to disk
# is effectively lost.  TankStructUpdate is the interval in seconds that the
# Tank Structure file on disk is updated.  The higher the interval, the more
# the tank data is that is potentially lost in a crash, the lower the interval
# the more the disk I/O that is required for wave_server to operate.

TankStructUpdate 1

# The file where TANK structures are stored

TankStructFile  j:\data\usgs\datafiles\p1000-1.str

# I open many files, one tracedata file for each SCNL channel to serve
# At 500 bytes/second, 1 channel requires 41.2 megabytes per day.
# NOTE: Record size must be multiple of 4 bytes or wave_serverV will crash
# with data misalignment.
# Also, record size must not be greater than MAX_TRACEBUF_SIZ, currently 4096,
# (defined in tracebuf.h)
#
#           SCNL    Record       Logo                  File Size   Index Size       File Name	    New
#          names   size  (TYPE_TRACEBUF2 only)         (megabytes) (max breaks)     (full path)      Tank

Tank    GUID EAG NC -- 528   INST_MENLO    MOD_WILDCARD       1         10000        j:\data\usgs\datafiles\p1001.tnk
Tank    IRG1 EAT NC --  528   INST_MENLO    MOD_WILDCARD       1         10000         j:\data\usgs\datafiles\p1002.tnk
Tank    IRG2 EAT NC --  528   INST_MENLO    MOD_WILDCARD       1         10000         j:\data\usgs\datafiles\p1003.tnk


# Advanced Options
# YES = 1, NO = 0, NO = (default)

#RedundantTankStructFiles  Set to 1 to use redundant tank struct files. (Recommended)
RedundantTankStructFiles 1

#RedundantIndexFiles  Set to 1 to use redundant tank index files. (Recommended)
RedundantIndexFiles      1


# Must be set if RedundantTankStructFiles = 1
#TankStructFile2  /tmp/p1000-2.str
TankStructFile2  j:\data\usgs\datafiles\p1000-2.str


#InputQueueLen:  The number of messages to buffer.  Messages are buffered
#in a queue.  They are added to the queue when they are pulled off of an
#earthworm message ring, they are removed from the queue when the main
#thread is ready to process them.  Depending on the CPU and disk speed
#of the machine you are using, this number should be about twice the
#number of tanks you are trying to serve.  Slower machines may need
#larger queues.
InputQueueLen 30


###################################
#           Other Optional Commands


#MaxMsgSize: Optional command to tell wave_server about TRACEBUF2 messages
# that could be larger than any going to tanks for this server. This
# may happen if you have two wave_servers and TRACEBUF2 sources that
# produce different size messages, e.g., ref2ew messages are 1064 bytes.
MaxMsgSize 1064

#Debug  Generates VERYVERYVERY large log files.
#Debug 1

#SocketDebug Set to 1 to get SOCKET_ew debug statements
SocketDebug 0

#PleaseContinue  Set to 1 to have wave_server continue, even if
#  there are errors during initialization
# PleaseContinue 1

#ReCreateBadTanks Set to 1 to have bad tanks re-created from scratch.
#ReCreateBadTanks 1

#SecondsBetweenQueueErrorReports   Minimum period of time between error
#  reports to statmgr due to the internal message queue being lapped,
#  and thus messages being lost.  Default is 60 seconds
#SecondsBetweenQueueErrorReports 30

#MaxServerThreads  Maximum of server threads to deploy to handle client
#  requests.  Default is 10.
#MaxServerThreads 10

#QueueReportInterval  The minimum number of seconds between
#  reports on internal queue high and low water marks.  The default is 30.
#QueueReportInterval 5

#AbortOnSingleTankFailure  Set to 0 to have wave_server continue even
#if there is a fatal error on a tank during normal processing.
#if this flag is not set to 0, wave_server will die if any type of
#IO error occurs on any tank.  If set to 1, wave_server will not exit
#unless there is a server wide error.
#AbortOnSingleTankFailure 1

#UsePacketSyncDb Uncomment entry and set to 1 to use embedded db functionality
# to manage asychronous trace buffer packets. Currently this is either on or off
# for all SNCLs.
#UsePacketSyncDb 1

#PacketSyncDbFile - Specifies name of database file to use. If not specified
# and UsePacketSyncDb == 1 then the default PCKTSYNC.SL3DB is used.
#PacketSyncDbFile "TB2PACKETS.SL3DB"

#PurgePacketSyncD Uncomment and specify one of the following to control
# how long out of sync data is kept in the database if UsePacketSyncDb=1.
# 1 : Purge data on startup
# 0 : Do not purge data on startup. Obsolete data is intermittently purged
# during the operation of wave_serverV is UsePacketSyncDb is 1.
#PurgePacketSyncDb 1

Module Index | Wave_ServerV Overview

Contact:
Questions? Issues? Subscribe to the Earthworm Google Groups List.