QWIDS/EIDS Installation
(and QDDS Migration)


Introduction
Data Provider
Data Server / Hub
Client Programs
Installation Samples
Message Test Utilities
Diagram of "Standard" QWIDS Setup




Introduction

     The QuakeWatch Information Distribution System (QWIDS) implementation of the Earthquake Information Distribution System (EIDS) provides end-to-end support for reliable XML-based messaging.  This document describes the installation and setup of components in the system.
     Legacy support for the CUBE message format is also provided, both on the client and server side.  As such, QWIDS can operate as a drop-in replacement for the QDDS messaging system.  Instructions for QDDS replacement are provided within the sections of this document.
     More complete documentation of QWIDS may be found in the "QuakeWatch Information Distribution System" summary document, and in the documentation for the various components.
     The "InstallationSamples" directory in the QWIDS distribution contains example configuration files for test installations.  Many of these configuration setups are referenced in the sections below.
     The QuakeWatch modules were developed as a next-generation earthquake notification system to alert users, in near real-time, of seismic data and vital earthquake-hazards information following significant events.  The modules have been enhanced and expanded to implement the EIDS specification put forth by the USGS.  QWIDS was developed and is maintained by ISTI.



Data Provider

     The entry point for messages into a QWIDS system is at a
QWServer component acting as a data provider.  In the "standard" setup of a QWIDS system, data providers make their messages available to serveral QWIDS data servers ("hubs"), and QWIDS client programs connect to the data servers to receive messages.  See the Diagram of "Standard" QWIDS Setup for a graphical illustration.  To create a data-provider installation, the following steps are recommended:

1. Copy the "QWServer" directory from the QWIDS distribution to the installation location.  If a QWIDS data provider is replacing or running in parallel with a QDDS data provider then the programs need to be on the same disk volume or drive.

2. The data-provider QWServer configuration file, in the installation directory at "conf/QWServerConfig.xml", must be customized for the specific installation.  Several sample configuration files are provided in the 'conf' directory; for example, the "conf/QWServerConfig_viafile.xml" file shows a configuration using a 'QWViaFile' feeder module.  The initial version of the
"conf/QWServerConfig.xml" file shows a configuration using a 'QWCorba' feeder module.  If a different feeder module is to be used then the existing "QWServerConfig.xml" file should be renamed (i.e., to "QWServerConfig_corba.xml") and the corresponding sample configuration file should be copied to "QWServerConfig.xml" (in the "conf" directory).
    
To duplicate the functionality of a QDDS data provider, a 'QWViaFile' feeder with a 'CubeAnssEQParser' entry needs to be setup, as demonstrated in the "conf/QWServerConfig_viafileanss.xml" sample configuration file.  To use this setup, rename the existing "QWServerConfig.xml" file and copy the "QWServerConfig_viafileanss.xml" file to "QWServerConfig.xml".  A QWIDS data provider setup in this manner will receive CUBE-format messages via discrete files, convert the messages to ANSS-EQ-XML format, and make the messages available to other QWIDS programs.  See below for more information on replacing a QDDS data provider.

3.
The data-provider QWServer "conf/QWServerConfig.xml" configuration file needs to be customized as follows:
     The "serverIdName" entry should be set to a name that is unique to the given installation.
     The "serverPortNum" and "notifSvcPortNum" entries should be set to TCP port values that are not used by other programs, and that are reachable by other QWIDS programs (not blocked by a firewall).  Note that the
"notifSvcPortNum" value must match the port number that the Notification Service (CORBA-event-channel) has been configured to run at (usually via the 'startNotif'/'runNotif.bat' script/batch file).
     The configuration file for a data-provider QWServer should contain a "defaultFdrSourceHost" entry, which will configure the QWServer to tag each incoming message with the specified feeder-data-source "host name" and a feeder-data-source message number.  The value specified in the 'defaultFdrSourceHost' entry should be different for each data provider in the QWIDS network.  The feeder-data-source values on each message act as a unique identifier, which is used to track the message throughout the rest of the QWIDS network.
     When determining "serverIDName" and "defaultFdrSourceHost" values, it may be necessary to contact the administrator of the QWIDS network in use to verify that the values are acceptable and unique.  The administrator will also need to know the host address and port number for the data provider.
     For more information on configuration parameters, see the "Server Configuration File" section of the QWServer Manual.  An example data-provider-QWServer configuration may be found in the "InstallationSamples/QWIDS_test/providers/QWServer_39177" directory in the QWIDS distribution.

4. A QDDS data provider may be replaced by a QWIDS QWServer data provider as follows:  For an initial test installation (that leaves the QDDS configuration untouched), the recommended setup is to have the QWServer process the message files after the QDDS program has processed them.  To set this up in the
QWServer "conf/QWServerConfig.xml" configuration file, the "inputDirName" entry in the "<QWFeederSettings>" element in the "<QWFeederMod>" element for the "QWViaFile" feeder should be set to the directory specified by the "STORAGE DIRECTORY" entry in the "QDDS.config" file for the QDDS program.  The result will be that after the QDDS program has processed each message file and placed it into its "STORAGE DIRECTORY" location, the QWServer will fetch and process the file (leaving it in the location specified by the "storageDirName" entry in the "<QWFeederSettings>" element in the QWServer "conf/QWServerConfig.xml" configuration file).  An example configuration may be found in the "InstallationSamples/QDDS_replace/provider/QWServer_provider" directory in the QWIDS distribution.
     For a permanent QWServer configuration, the setup should be changed to make the message files be processed by the QWServer instead of the QDDS program.  The data source providing the message files should be configured to place the files in the location specified by the
"inputDirName" entry in the "<QWFeederSettings>" element in the "<QWFeederMod>" element for the "QWViaFile" feeder (in the QWServer "conf/QWServerConfig.xml" configuration file).  Care should be taken to make sure that the QDDS program does not also process input files from the same location.  If desired, the functionality of the QDDS program can be preserved by setting the "POLL DIRECTORY" entry in the "QDDS.config" file to the directory specified by the "storageDirName" entry in the "<QWFeederSettings>" element in the QWServer "conf/QWServerConfig.xml" configuration file.  With this setup, the message files will be processed first by the QWServer and then by the QDDS program.
    
For more information on feeder settings, see the "QuakeWatch Feeder Modules" section of the QWServer Manual.
     Note that if a single installation of a QDDS program is operating as both a "hub" (sending messages) and a "leaf" (receiving messages), the QWIDS equivalent would consist of two separate installations, one for a data provider and one for a client program.

5. A data-provider QWServer installation may be configured to require that a username/password login be supplied by the QWIDS programs that access the server.  The configuration parameters for this are described in the "Password Database Configuration Parameters"
section of the QWServer Manual.  The easiest method is via the 'localPasswordFile' parameter.

6. The QWIDS data provider is usually started via the "startAll" script (Unix) or "runAll.bat" batch file (Windows)
.  See the "Running QWServer" section of the QWServer Manual for more information.



Data Server / Hub

     The central component in the QWIDS messaging system is a QWServer acting as a data server, or "hub".  The data server receives messages from any number of QWIDS data providers, stores them in a persistent archive, and delivers them to any number of QWIDS client programs (in real time or upon request).  To install a data-server QWServer, the following steps are recommended:

1. Copy the "QWServer" directory from the QWIDS distribution to the installation location.

2. The data-server QWServer configuration file, in the installation directory at "conf/QWServerConfig.xml", must be customized for the specific installation.  For a QWServer acting as a data server, one or more 'QWRelay' feeders will be specified in the configuration file.  (The 'QWRelay' feeders implement the connections to the QWIDS data providers.)  A good starting point is the "conf/QWServerConfig_relay.xml" sample configuration file.  To make use of the this configuration, rename the existing
"QWServerConfig.xml" file (i.e., to "QWServerConfig_corba.xml") and copy the "QWServerConfig_relay.xml" file to "QWServerConfig.xml" (in the "conf" directory).
     The configuration file may contain several "<QWFeederMod>" entries for 'QWRelay' feeders, and each one should be customized as follows:
a. The 'Name' attribute should be different for each feeder.

b. The 'LogFileName' attribute must specify a different log file for each feeder.

c. The "serverHostAddress" setting should specify the host address of the data-provider QWServer that the feeder will connect to.

d. The "serverPortNumber" setting should specify the port number of the data-provider QWServer that the feeder will connect to.

e. The "alternateServersList" setting should be set to an empty string ("").

f. The "altServersEnabledFlag" setting should be set to 'false'.

g. If the data-provider QWServer has been configured to require a username/password login then the "loginInfoFileName" setting should be set to the name of a server login information file containing a valid login.
No special setup is needed for QDDS-data-server replacement, as all the QDDS-specific changes are made to the QWIDS data providers and clients.  For more information on feeder settings, see the "QuakeWatch Feeder Modules" section of the QWServer Manual.

3. In the "standard" setup of a QWIDS system, each data server receives messages from all data providers.  See the Diagram of "Standard" QWIDS Setup for a graphical illustration.  It is also possible to "cross-connect" data servers to each other (via additional 'QWRelay' feeders) for added redundancy, with the cost of additional message traffic.  When data servers are cross-connected, it is especially important that all messages are tagged with feeder-data-source values when they enter the QWIDS system at the data provider.  (The feeder-data-source values allow the data servers to effectively identify and reject duplicate messages.)

4.
The data-server QWServer "conf/QWServerConfig.xml" configuration file needs to be customized as follows:
     The "serverIdName" entry should be set to a name that is unique to the given installation.
     The "serverPortNum" and "notifSvcPortNum" entries should be set to TCP port values that are not used by other programs, and that are reachable by other QWIDS programs (not blocked by a firewall).  Note that the
"notifSvcPortNum" value must match the port number that the Notification Service (CORBA-event-channel) has been configured to run at (usually via the 'startNotif'/'runNotif.bat' script/batch file).
     For more information on configuration parameters, see the "Server Configuration File" section of the QWServer Manual.  An example data-server-QWServer configuration may be found in the "InstallationSamples/QWIDS_test/QWServer_hub" directory in the QWIDS distribution.

5. A data-server QWServer installation may be configured to require that a username/password login be supplied by the QWIDS programs that access the server.  The configuration parameters for this are described in the "Password Database Configuration Parameters"
section of the QWServer Manual.

6. The QWIDS data server is usually started via the "startAll" script (Unix) or "runAll.bat" batch file (Windows)
.  See the "Running QWServer" section of the QWServer Manual for more information.



Client Programs

     Many types of QWIDS client programs are available.  See the "Persistent Clients" section of the QWIDS Summary document for descriptions of the available client programs.  The CISN Display is also an example of a QWIDS-compatible client.

      To replace a QDDS program operating as a "leaf" (receiving messages), the QWCubeOutClient program should be used.  The output of this client will be CUBE-format messages in discrete files.  To create a QWCubeOutClient installation, the following steps are recommended:

1. Copy the "QWCubeOutClient" directory from the QWIDS distribution to the installation location.

2. The QWCubeOutClient configuration file, in the installation directory at "conf/QWCubeOutClientConfig.xml", needs to be customized as follows:
     The "outputMsgFilesDir" entry should be set to the directory location where the received messages are to be delivered (as CUBE-format messages in discrete files).
    The "serverHostAddress" entry should specify the host address of the data-server QWServer that the client will connect to.
    
The "serverPortNumber" entry should specify the port number of the data-server QWServer that the client will connect to.
     The "altServersEnabledFlag" entry is set 'true' to allow the client to switch to an alternate server if the connection fails; 'false' to only allow the client to connect to the specified server.
     The "alternateServersList" entry may be used to specify alternate servers; or it may be set to an empty string for none.  (The client may also fetch a list of alternate servers from the connected server.)
     See the
QWCubeOutClient documentation for more information on its configuration settings.

3. After the QWCubeOutClient is installed and configured, it may be started via the "run" script (Unix) or "run.bat" batch file (Windows).  An example QWCubeOutClient configuration may be found in the "InstallationSamples/QDDS_replace/QWCubeOutClient" directory in the QWIDS distribution.




Installation Samples

    
The "InstallationSamples" directory in the QWIDS distribution contains example setups of configuration files.  The setups may also be made runnable by copying in the program jar files; the "copyJars" script (Unix) or "copyJars.bat" batch file (Windows) may be executed to copy in all the necessary program jars.
     The "QDDS_replace" directory contains a test version of a setup with a QWIDS data provider (that processes message files after a QDDS program processes them), a data server, and a QWCubeOutClient.  The "startTestAll" script (Unix) or "runTestAll.bat" batch file (Windows) is used to start all the programs in the setup, and the "stopTestAll" script (Unix) is used to stop all the programs.  (Under Windows, the programs are stopped by closing the command-prompt window.)  While the programs are running, CUBE-format message files that are copied into the "QDDS_replace/provider/QDDS_provider/polldir" directory should be processed through the test "network" and end up as CUBE-format message files in the "QDDS_replace/QWCubeOutClient/cubeOutData/msgOutput" directory.
     The "QWIDS_test" directory contains a test version of a QWIDS setup with four data providers, a data server, and several client programs.  The programs are started and stopped in same way as in the "QDDS_replace" setup. 
While the programs are running, CUBE-format message files that are copied into the "viaFileData/msgInput" directory of any of the QWServer providers should be processed through the test "network" and end up being processed by the client programs.



Message Test Utilities

    
Several test utilities are available to simulate the translation of CUBE-format messages to and from XML-format messages.  Scripts and batch files are provided for executing these utilities.

     In the QWServer distribution are the following:
runCubeToQuakeML - Unix script for launching the CubeToQuakeML test utility.
runCubeToQuakeML.bat - Windows batch file for launching the CubeToQuakeML test utility.
runCubeToAnssEQXML - Unix script for launching the CubeToAnssEQXML test utility.
runCubeToAnssEQXML.bat - Windows batch file for launching the CubeToAnssEQXML test utility.
runCubeToQWXML - Unix script for launching the CubeToQWXML test utility.
runCubeToQWXML.bat - Windows batch file for launching the CubeToQWXML test utility.
     CubeToQuakeML converts CUBE-format messages to QuakeML-format messages. The CUBE-format messages may be entered as command-line arguments or via 'stdin'.  The generated XML-format messages are sent to 'stdout'.
     CubeToAnssEQXML converts CUBE-format messages to ANSS-EQ-XML-format messages. The CUBE-format messages may be entered as command-line arguments or via 'stdin'.  The generated XML-format messages are sent to 'stdout'.
     CubeToQWXML converts CUBE-format messages to QuakeWatch-XML-format messages.  The CUBE-format messages may be entered as command-line arguments or via 'stdin'.  The generated XML-format messages are sent to 'stdout'.
 
     In the QWCubeOutClient distribution are the following:
runCubeOutFromXML - Unix script for launching the CubeOutFromXML test utility.
runCubeOutFromXML.bat - Windows batch file for launching the CubeOutFromXML test utility.
     CubeOutFromXML converts XML-format messages to CUBE-format messages.  The given XML-format messages may be in QuakeML, ANSS-EQ-XML or "QuakeWatch" format.  The XML-format messages may be entered as command-line arguments, a single XML-format message may be entered via 'stdin', or a file containing a single XML-format message may be specified by entering "-i" followed by the file name as command-line arguments.  The 'quakeMessage' (QuakeML format), 'EQMessage' (ANSS-EQ-XML format) or 'Event' (QuakeWatch format) element in the message may be (optionally) surrounded by 'DataMessage' and 'QWmessage' elements.  The generated CUBE-format messages are sent to 'stdout'
.



Diagram of "Standard" QWIDS Setup





4/23/2010 - Eric Thomas, Instrumental Software Technologies, Inc.