• Introduction
• Notification Service / CORBA-Event-Channel
• Installing QWServer
• Running QWServer / Requirements
• Server Configuration File
• Additional Server Configuration Parameters
• Password Database Configuration Parameters
• Status Report Configuration Parameters
  
• QuakeWatch Feeder Modules
• QuakeWatch Outputter Modules
  
• Setting Up a Slave MySQL Server for CISN Login
• Checking If a Slave MySQL Database is Synchronized
  
• Setting Up a QWServer with a QDDS Feeder
• Firewall Issues
• Troubleshooting
• QuakeWatch Server Login Information File
• Feeder-Data-Source Message Tracking System
• Message Signing Implementation
• Client / Server Connection Notes
• Server Cache/Archive Notes
• Message Format
• Example QuakeWatch Server Configuration File
• Example Feeder-Modules Configuration File
• Example Client-Versions-Information File
• QuakeWatch Messaging System Diagram
• Revision History Notes
• See Also

     The QuakeWatch Information Distribution System (QWIDS) provides an end-to-end implementation for reliable XML-based messaging.  Its features include multi-platform support, a high level of configurability, persistent archiving of messages, and missed-message tracking/recovery.  QWIDS was 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 QuakeWatch server operates as a "hub", receiving messages from one or more sources and passing them on to any number of QuakeWatch-client applications.  It receives its data from configurable "feeder" modules.
     The messages are then passed along to QuakeWatch clients via a Notification Service CORBA-event-channel.  The QuakeWatch server provides support for resending requested messages, allowing clients to catch-up on missed messages.
     The QuakeWatch server is written entirely in Java, allowing it to run on all major operating systems and hardware.  The messaging system uses a leading open-source version of the industry-standard Common Object Request Broker Architecture (CORBA).

     Messages are delivered from the QuakeWatch server to its clients using a Notification Service CORBA-event-channel.  The CORBA-event-channel provides a "one to many" relationship, allowing the server to service many clients without degrading its performance.  A QuakeWatch client program first establishes a connection to the QuakeWatch server, and then the server provides the client with the location of the CORBA-event-channel.
     New messages are "pushed" to the client via the CORBA-event-channel.  QuakeWatch clients also "check in" with the QWServer by calling a connection-status CORBA method on a periodic basis, and clients may request previously-sent messages from the QWServer.  See the "QuakeWatch Messaging System Diagram" for a visual representation of the system.
     The Notification Service executes as a separate program from the QuakeWatch server (see the "Running QWServer" section for more information on startup).  When the server starts up, it finds the Notification Service and creates a CORBA-event-channel for sending messages, and stores a locator for the CORBA-event-channel in a local file (whose name is specified via the 'mainEvtChLocFile' configuration parameter.)  If the created CORBA-event-channel is still available the next time the server starts up then it will be reused.

     The QuakeWatch server distribution is available in archived form as a ".zip" file.  The following files and directories should be present after the archive is unpacked:

     Use of the QuakeWatch server requires that a Java Version Machine (JVM) version 1.8 or higher be available on the host system.

     The server configuration file (including feeder modules) must be customized for each installation.  See the sections that follow for more information.

     Before running the QuakeWatch server, the Notification Service (CORBA-event-channel) program must be started.  The Notification Service (CORBA-event-channel) program may be started via the startNotif script (Unix) or runNotif.bat batch file (Windows).  The QuakeWatch server program may be started via the startQWS script (Unix) or runQWS.bat batch file (Windows).  Both programs may be launched with a single command via the startAll script (Unix) or runAll.bat batch file (Windows).  T he startAllNum script (Unix) or runAllNum.bat batch file (Windows) may be used to launch both programs with numeric-IP use enabled (see the 'publishNumericIPFlag' parameter description for more information).  These script and batch files must be run from the directory where the QuakeWatch server program was installed.

     Under Unix, the Notification Service (CORBA-event-channel) program may be terminated via the stopNotif script, the QuakeWatch server program may be terminated via the stopQWS script, and both programs may be terminated with a single command via the stopAll script.  (Note that the "start" and "stop" scripts may need to be made executable via the "chmod" command.)
     Under Unix, both programs may be launched or terminated via the startStopAll script by giving it the parameter value 'start' or 'stop'.  The startStopAllNum script operates in the same way except with numeric-IP use enabled (see the 'publishNumericIPFlag' parameter description for more information).  If the startStopAll or startStopAllNum script is not run from the directory where the QuakeWatch server program was installed then the environment variable "QWSERVERDIR" should be set to the location where the QuakeWatch server program was installed.
     The process-ID of the programs may be determined by using a command like "ps -Afwwu uname | grep java", where "uname" is the user-name that the programs were run under.  The "start" scripts that start up the servers create ".pid" files that contain the process-ID numbers for the processes.  These files are used when terminating the servers via the "stop" scripts.

     Under Windows, the programs will each run in a console window.  Selecting the console window and hitting "Ctrl-C" will terminate the program.

     The Notification Service (CORBA-event-channel) program may be configured to run at a port number other than the default (39988) by inserting the "-p=###" parameter into the launch command for the program (i.e., 'java -Xms16m -Xmx256m -jar ISTINotifServer.jar -g=1 -p=31988 &').  It may be configured to run at a specified host address by inserting the "-a=address" parameter into the launch command for the program (i.e., 'java -Xms16m -Xmx256m -jar ISTINotifServer.jar -g=1 -a="131.215.220.4" &').  An effective way of doing this for a given installation is to edit the 'startNotif' script (Unix) or 'runNotif.bat' batch file (Windows).

     The QWServerConfig.xml file (found in the "conf" directory) contains the configuration parameters for the QuakeWatch server.  See the "Example QuakeWatch Server Configuration File" section for a sample file.  An alternate location and/or name for the server configuration file may be specified by supplying "--configFile" as the first command-line parameter and the path/file name for the configuration file as the second command-line parameter to the program.   When any parameter in the configuration file is changed, the server must be restarted for the change to take effect.
     The configuration file is in XML format, with all of the information inside of a "<QWServerConfig>" element.  The main configuration parameters for the server reside inside of the "<Settings>" element, and are described below.
     See the "QuakeWatch Feeder Modules" section for details on the QWFeederMod element that is used to configure the QuakeWatch server feeder modules.

serverIdName = "name"
     The ID name string for the server.  This server-ID name should uniquely identify the server installation.  The name will be passed along to clients connecting to the server.

serverPortNum = ##
     The port number specification for the server.  Clients connecting to the server will specify this port address.  If this parameter is not specified then the port address will default to 39977.  Note that if the specified port value is less than 1024 then special operating-system administrator privileges may be required to run the server.

notifSvcPortNum = ##
     An optional port number specification for the Notification Service (CORBA-event-channel) that determines where the server will expect to find the Notification Service program.  If the Notification Service has been configured to run at a port number other that the default (39988), then this parameter must be set to the port number value.  If this parameter is not specified then the value will default to 39988.  If this parameter is set to 0 then the server will not use a CORBA-event-channel.  To configure the Notification Service program to run at a port number other than the default (39988), the "-p=##" parameter is inserted into the launch command for the program (i.e. "java -Xms16m -Xmx256m -jar ISTINotifServer.jar -g=1 -p=38988 &").

altServerIdsList = "hostAddr:port,hostAddr:port,..."
     The list of alternate server-IDs to be passed along to clients connecting to the server.  If a client connected to the server detects a loss of connectivity, the client will attempt to connect to the servers on the list.  Each item in the list contains a host address in name (i.e. "www.caltech.edu") or numeric-IP (i.e. "131.215.220.4") form, followed by a numeric port-address value; with the items separated by commas.  If this parameter is not specified then no alternate server-IDs are used.

allowDuplicatesFlag = true/false
     Configures whether the server will accept or reject duplicate messages.  The combination of this and the 'checkDupFdrSourceFlag' parameter are used to configure how the server handles duplicate messages, where a duplicate message is one whose payload (in the "DataMessage" element) matches that of a previously-received message in the server's cache.  See the table below for details.  If this parameter is not specified then the value will default to 'false'.

     The QWServer may be configured to generate and deliver status reports containing information about the server's operation, errors and connected clients.  The status reports may be written to a log file, made available via the client-services connection, and/or sent to a remote machine (via 'scp' copy).   The configuration parameters for doing this are described below.

stRptItvlMins = ##
     Sets the status-report interval, in minutes.  For any status-report data to be generated, this parameter must be set to a value greater than zero.  This parameter may be specified as a floating point value (such as 1.5 minutes).  If this parameter is not specified then the value will default to 0.0 (no reports generated).

stRptTrkLogLevel = "level"
     Sets the minimum tracking log level for status reports.  Server log messages that are at this level or greater will be entered into the reports.  For example, if this parameter were set to "Info" then log messages at the "Info" and "Warning" levels would be entered.  If this parameter is not specified then the value will default to "Warning".

stRptTrkLogCount = ##
     Sets the maximum number of tracked log messages that will be retained for status reports.  When more than this number of tracked log messages occur, older messages will be discarded.  If this parameter is not specified then the value will default to 10.

stRptTrkLogHours = ##
     Sets the maximum age (in hours) for tracked log messages to be retained for status reports.  When the age of a tracked log messages becomes older that this value, it is discarded.  If this parameter is not specified then the value will default to 24 hours.

stRptOnLogFlag = true/false
     If this parameter is set to 'true' then a status report will be generated immediately whenever a tracked log message is entered.  If this parameter is not specified then the value will default to 'true'.

stRptClientsFlag = true/false
     If this parameter is set to 'true' then a list of currently-connected clients will be included in generated status reports.  If this parameter is not specified then the value will default to 'true'.

stRptClientQueriesFlag = true/false
     Setting this parameter to 'true' will enable the querying of status reports via a client-services connection.  (This will allow the QWStatusProcessor program to directly fetch status reports from the server.)  If this parameter is not specified then the value will default to 'true'.

stRptLocalFile = "filename"
     Specifies the name of a local status-report log file that will receive copies of generated status reports.  A date code in the form "_yyyymmdd" will be inserted into the name, and a new log file will be used each day.  If this parameter is not specified or is set to an empty string then no local status-report log file will be generated.

stRptFilesMaxAge = ##
     The maximum age, in days, for local status-report log files generated by the server.  Local status-report log files older than this value will be automatically deleted; unless the value is zero, in which case the log files will never be deleted.  If this parameter is not specified then the value will default to 7 days.

stRptRemoteDir = "directory"
     If generated status reports are to be delivered as files to a remote machine via 'scp' then this parameter must be set to the destination directory path.  If this parameter is not specified or is set to an empty string then status reports will not be delivered as files to a remote machine.

stRptRemoteFName = "filename"
     If generated status reports are to be delivered as files to a remote machine via 'scp' then this parameter may be used to specify to the destination file name.  If this parameter is not specified and status reports are delivered as files to a remote machine then the file name will be automatically generated using the 'serverIdName' parameter value.  A current timestamp is added to the name on each delivered file (to make each file name unique).

stRptRemoteHost = "hostAddress"
     If generated status reports are to be delivered as files to a remote machine via 'scp' then this parameter should be set to the host address of the remote machine.  If this parameter is not specified then the value will default to an empty string ("").

stRptRemoteUser = "username"
     If generated status reports are to be delivered as files to a remote machine via 'scp' then this parameter should be set to the username of an SSH login on the remote machine.  If this parameter is not specified then the value will default to an empty string ("").

stRptRemAuthKeyFile = "filename"
     If generated status reports are to be delivered as files to a remote machine via 'scp' then this parameter should be set to the authorization keyfile for an SSH login on the remote machine.  If this parameter is not specified then the filename will default to ".ssh/id_rsa" in the user-home directory.

stRptRemChkHostFlag = true/false
     If generated status reports are to be delivered as files to a remote machine via 'scp' then this parameter may be set 'true' to require that the host address for the remote machine is listed among those in the ".ssh/known_hosts" file in the user-home directory on the local machine.  If this parameter is not specified then the value will default to 'false' (all host addresses accepted).

     The QWServer may be configured to use a "password database" to verify client-connection login information.  The password-data parameters for the server reside inside of the "<Settings>" element of the server configuration file, and are described below.  See the "Setting Up a Slave MySQL Server for CISN Login" section for information on how to configure the password database.

pwdDatabaseHostAddress = "hostAddress"
     The host address specification for the machine hosting the client-login password database.  If the client-login password database is hosted on the same machine as the QuakeWatch server then a value of "localhost" should be used.  If this parameter is not specified or is set to an empty string then the value "localhost" will be used.

pwdDatabasePortNumber = "###"
     The port number specification for the machine hosting the client-login password database.  The port number is configured as part of the client-login password database administration.  If this parameter is not specified or is set to an empty string then the value "3306" will be used.

pwdDatabaseIdentifier = "identifier"
     The database-identifier string for the client-login password database.  The database identifier is configured as part of the client-login password database administration.  If this parameter is not specified or is set to an empty string then a client-login password database will not be used by this QuakeWatch server.

pwdDatabaseUsername = "username"
     The database-access username for the client-login password database.  The username is configured as part of the client-login password database administration.

pwdDatabasePassword = "password"
     The database-access password for the client-login password database.  The password is configured as part of the client-login password database administration.

localPasswordFile = "pathname"
     The path and file name for a local file containing client-login password information.  The file provides an alternate method of specifying client-login information (instead of the database).  If both the local file and the database are configured then both will be used and the entries in the local file will take precedence.  The file contains one line per client-login entry, with each line in the format "username=encryptedPwd", where "encryptedPwd" is the encrypted form of the password (using Unix-style crypt).  The following command may be used to create an encrypted password for use in this file:

		  java -cp QWServer.jar com.isti.util.JCrypt username password
	

     If the 'localPasswordFile' parameter is not specified or is set to an empty string then a local client-login password file will not be used by this QuakeWatch server.  A sample local-password file, "test/TestLocalPwdFile.txt", is included with the QWServer distribution.

     The QuakeWatch server receives its messages from feeder modules, which are configured via one or more "<QWFeederMod>" elements in the server configuration file.  They may also be specified in a dynamic feeder-modules configuration file (see the "feederModulesCfgFile" parameter).  These modules are available:

• The "QWRelayFeeder" receives its messages from another QuakeWatch server.
• The "QWPdlFeeder" receives its messages from a Product Distribution Layer ('PDL') hub.
  
• The "QWViaFileFeeder" receives messages via files placed into an "input" directory (similar to how a QDDS "hub" operates). 
• The "QWCorbaFeeder" receives messages by way of a CORBA method.
• The "QDDSFeeder", "QddsAnssEQFeeder" and "QddsQuakeMLFeeder" modules operate as a "leaf" on the QDDS network, receiving and translating new event messages. 

Note:  If the "QWPdlFeeder" is used, a copy of the "ProductClient.jar" file from the PDL distribution must reside in the QWServer program directory.

Any number of  "<QWFeederMod>" elements may specified, and any combination of feeder types may be included.  The following attributes of this element are common to all feeder modules.

Name = "feederName"
     The name associated with the feeder module.  The QWRelay feeder is usually named "QWRelay" and the QDDS feeder is usually named "QDDS".

Class = "feederClassSpec"
     The Java class specification for the feeder module.  This is used to by the server to load the feeder module.  The following table shows the value used for each type of feeder module.  For example, a value of "com.isti.quakewatch.server.QWRelayFeeder" would specify the 'QWRelay' feeder module.

Params = "params"
     A string of feeder-specific parameters to be entered into the feeder module.  For the QDDS feeder the location of the QDDS-leaf configuration file, "conf/QDDS.config", is entered.

LogFileName = "logFileName"
     The log file to be used by the feeder module.  For the QDDS feeder, "log/QDDSFeeder.log" is usually used.  For the QWRelay feeder, "log/QWRelayFeeder.log" is usually used.  A date code in the form "_yyyymmdd" will be inserted into the name, and a new log file name will be used each day.  When more than one feeder is specified, each feeder must have a separate log file.

LogFileLevel = "level"
     The message level for the feeder's log file output.  The allowed values are "NO_MSGS", "Error", "Warning", "Info", "Debug", "Debug2", "Debug3", "Debug4", "Debug5" and "ALL_MSGS".  If this attribute is not specified then the value will default to "Error".

ConsoleLevel = "level"
     The message level for the feeder's console output.  The allowed values are "NO_MSGS", "Error", "Warning", "Info", "Debug", "Debug2", "Debug3", "Debug4", "Debug5" and "ALL_MSGS".  If this attribute is not specified then the value will default to "Error".


QWFeederSettings:  Within the QWFeederMod element may reside a "<QWFeederSettings>" element containing feeder-specific settings.  This element is not used by the QDDS, QddsAnssEQ and QddsQuakeML feeders.

For the QWRelay feeder, the "QWFeederSettings" element may contain the following settings:

serverHostAddress = "hostAddress"
     The host-address specification for the server from which the feeder will receive messages.  The address may be in name (i.e. "www.caltech.edu") or numeric-IP (i.e. "131.215.220.4") form.  If this parameter is empty or is not specified and the 'altServersEnabledFlag' parameter is 'true' then one of the alternate servers will be chosen at random (if any are specified) and used as the server.

serverPortNumber = ##
     The port-number specification for the server from which the feeder will receive messages.  If this parameter is not specified then the value will default to 39977.

webServicesServerFlag = true/false
     Set 'true' to configure the connection as being to a QuakeWatch Web Services Server (as opposed to a CORBA-based QWServer).  If this parameter is not specified then the value will default to 'false' (CORBA-based QWServer).  Note that a copy of the QuakeWatch Web Services Manager "jar" file may be needed to provide support for connecting to a QuakeWatch Web Services Server.

loginInfoFileName = "filename"
     The name of the server login information file.  This file may be used to specify the username and password used to validate the connection to the server from which the feeder will receive messages.  If this parameter is not specified then the filename will default to "conf/ServerLoginInfo.dat".  If this parameter is set to an empty string ("") or if the specified file is missing then a blank username and password will be used.  For more information on this file, see the "QuakeWatch Server Login Information File" section.

alternateServersList = "hostAddr:port,hostAddr:port,..."
     The list of alternate host-server-IDs that may be used by the feeder.  If the feeder detects a loss of connectivity then it will attempt to connect to the servers on the list.  Each item in the list contains a host address in name (i.e. "www.caltech.edu") or numeric-IP (i.e. "131.215.220.4") form, followed by a numeric port-address value; with the items separated by commas.  Note that if the keepDefaultAltServersFlag parameter is 'false' then the feeder may instead use a new list fetched from the current host server.

altServersEnabledFlag = true/false
     Set 'true' to enable the feeder to switch to an alternate server when a loss of connectivity is detected.  If 'false' then the feeder will only connect to the server specified via the 'serverHostAddress' and 'serverPortNumber' parameters.  If this parameter is not specified then the value will default to 'true' (alternate servers enabled).

keepDefaultAltServersFlag = true/false
     Set 'true' to configure the feeder to only use the list of alternate host-server-IDs specified by the 'alternateServersList' parameter and never fetch a new list from the current host server.  If 'false' then the list may be overwritten by a new list fetched from the current host server.  If this parameter is not specified then the value will default to 'false' (fetch alternate servers list).

maxServerEventAgeDays = 3.0
     The maximum number of day's worth of messages that the feeder may fetch from its host server.  This parameter may be specified as a floating point value (such as 1.5 days).  If this parameter is not specified then the value will default to 15.0 days.

For the QWPdl feeder, the "QWFeederSettings" element may contain the following settings:

pdlServerHost = "hostAddress"
     The IP address or hostname where a PDL EIDS Server with notifications is running.  The address may be in name (i.e. "www.caltech.edu") or numeric-IP (i.e. "131.215.220.4") form.  If this parameter is not specified then it will default to "ehppdl1.cr.usgs.gov".

pdlServerPort = ##
     The port where a PDL EIDS Server with notifications is running.  If this parameter is not specified then the value will default to 39977.

pdlAlternateServers = "hostAddr:port,hostAddr:port,..."
     A list of alternate host-server-IDs that may be used by the feeder.  If the feeder detects a loss of connectivity then it will attempt to connect to the servers on the list.  Each item in the list contains a host address in name (i.e. "www.caltech.edu") or numeric-IP (i.e. "131.215.220.4") form, followed by a numeric port-address value; with the items separated by commas.  If this parameter is not specified then it will default to "ehppdl2.wr.usgs.gov:39977".

pdlTrackingFile = "filename"
     The name of the tracking file used by the PDL-client receiver.  If this parameter is not specified then it will default to "pdldata/receiver_pdl_tracking.dat".

pdlMaxServerEventAgeDays = #.#
     The maximum number of day's worth of messages that the feeder may fetch from its host server.  This parameter may be specified as a floating point value (such as 1.5 days).  If this parameter is not specified then the value will default to 3.0 days.

pdlReceiverStorage = "path"
     The path for the directory used by the PDL-client receiver for storage.  If this parameter is not specified then it will default to "pdldata/receiver_storage".

pdlReceiverIndex = "filename"
     The name of the index file used by the PDL-client receiver for storage.  If this parameter is not specified then it will default to "pdldata/receiver_index.db".

pdlListenerIndex = "filename"
     The name of the index file used by the PDL-client listener for storage.  If this parameter is not specified then it will default to "pdldata/listener_index.db".

pdlCleanupInterval = ##
     The interval (in milliseconds) of how often the PDL-client receiver will check for and remove stored products that are older than the age specified by the 'pdlStorageAge' parameter.  If this parameter is not specified then the value will default to 900000 (15 minutes).

pdlStorageAge = ##
     The maximum age (in milliseconds) for stored products held by the PDL-client receiver.  If this parameter is not specified then the value will default to 900000 (15 minutes).

pdlMaxTries = ##
     The maximum number of delivery attempts PDL receiver should make.  If this parameter is not specified then the value will default to 5.

pdlRetryDelay = ##
     The number of milliseconds the PDL receiver should wait between delivery attempts that fail.  If this parameter is not specified then the value will default to 30000 (30 seconds).

dyfiUrlPrefixStr = "str"
     The prefix string used to build Did-You-Feel-It product URLs.  If this parameter is not specified then it will default to "http://earthquake.usgs.gov/earthquakes/dyfi/events/".

dyfiUrlSuffixStr = "str"
     The suffix string used to build Did-You-Feel-It product URLs.  If this parameter is not specified then it will default to "/us/index.html".

shakemapUrlPrefixStr = "str"
     The prefix string used to build ShakeMap-product URLs.  This is used in combination with the product-ID to build a ShakeMap-product-link URL string in the form:   {shakemapUrlPrefixStr}<TYPE>/<CODE>/<SOURCE>/<UPDATETIME>{shakemapUrlSuffixStr}
     If this parameter is not specified then it will default to "http://earthquake.usgs.gov/product/".

shakemapUrlSuffixStr = "str"
     The suffix string used to build ShakeMap-product URLs.  This is used in combination with the product-ID to build a ShakeMap-product-link URL string in the form:   {shakemapUrlPrefixStr}<TYPE>/<CODE>/<SOURCE>/<UPDATETIME>{shakemapUrlSuffixStr}
     If this parameter is not specified then it will default to "/intensity.html".

pdlReceiverLogLevel = "level"
     The log level for the PDL-client receiver; one of:  "OFF", "SEVERE", "WARNING", "INFO", "CONFIG", "FINE", "FINER", "FINEST", "ALL".  If this parameter is not specified then it will default to "INFO".

For the QWViaFile feeder, the "QWFeederSettings" element may contain the following settings:

inputDirName = "directoryName"
     The directory that will be polled for input files.  If this parameter is not specified then the value will default to "msgInput".

storageDirName = "directoryName"
     The directory into which files will be placed after they have been processed.  If this parameter is not specified then the value will default to "msgSave".

processDirName = "directoryName"
     The directory that the feeder will move input files into while they are being processed.  If this parameter is not specified then the value will default to "msgProcess".

inputPollDelayMS = ##
     The number of milliseconds that the feeder will delay between polls of the input directory.  If this parameter is not specified then the value will default to 1000 milliseconds.

storageAgeSecs = ##
     The number of seconds that the feeder will hold processed files in the "storage" directory before deleting them.  A value of 0 will configure the feeder to delete the files immediately after processing them.  If this parameter is not specified then the value will default to 86400 seconds (1 day).

feederParserClass = "feederParserClassSpec"
     The Java class specification for a feeder-parser to be used by this feeder.  This parameter may be set to:
  "com.isti.quakewatch.server.CubeQuakeMLParser" to have incoming messages converted from CUBE format to QuakeML format;
  "com.isti.quakewatch.server.CubeAnssEQParser" to have incoming messages converted from CUBE format to ANSS-EQ-XML format;
  "com.isti.quakewatch.server.CubeFormatParser" to have incoming messages converted from CUBE format to QuakeWatch "QWmessage" XML format.
     If this parameter is not specified then incoming messages will be passed through without modification.

For the QWCorba feeder, the "QWFeederSettings" element may contain the following settings:

feederPortNumber = ##
     The port number that this CORBA feeder will listen on.  If this parameter is not specified then the value will default to 38800.

feederParserClass = "feederParserClassSpec"
     The Java class specification for a feeder-parser to be used by this feeder.  This parameter may be set to:
  "com.isti.quakewatch.server.CubeQuakeMLParser" to have incoming messages converted from CUBE format to QuakeML format;
  "com.isti.quakewatch.server.CubeAnssEQParser" to have incoming messages converted from CUBE format to ANSS-EQ-XML format;
  "com.isti.quakewatch.server.CubeFormatParser" to have incoming messages converted from CUBE format to QuakeWatch "QWmessage" XML format.
     If this parameter is not specified then incoming messages will be passed through without modification.

corbaloc:iiop:1.2@localhost:38800/QWFeeder

     A QuakeWatch server may be configured to deliver messages via one or more outputter modules.  As of version 0.65Beta, the QWCorbaOutputter is available.
     Note that a given QuakeWatch server may be configured use both outputters and the standard QWServices interface for QuakeWatch clients.

     This section describes the process of setting up a new slave MySQL server for use with the CISN login system.  The slave servers are read-only database servers that replicate the data from the single master (read/write) server.

• On the master server
1. Using the "root" user, add a row to the "host" table in the "mysql" database for the new host:

   insert into host (Host) values('new.host.name');

• On the slave server
1. Download the proper MySQL 4.1 distribution from www.mysql.com
2. Expand the MySQL distribution to /usr/local (or another destination if you prefer)
3. Follow the instructions in INSTALL-BINARY located in the directory that the distribution expanded into
4. Add the following line to /etc/my.cnf in the [mysqld] section

   server-id=XXX

   where XXX is an ID unique to this MySQL server. The master has been set up with an ID of 1, and the first slave has been set up with an ID of 100.
   If this file does not exist, you can safely make it look like:

   [mysqld]
   server-id=XXX

5. Connect to the slave MySQL server using the "mysql" client, and enter the following:

   CHANGE MASTER TO MASTER_HOST='www1.cisn.org', MASTER_USER='replicator', MASTER_PASSWORD='foobar';

6. While still connected to the slave MySQL server, enter the following:

   LOAD DATA FROM MASTER; START SLAVE;

   This will create all databases and tables, and start replication.
7. Create a user on the slave database for the QWServer to use, for validating QW users by running the following:

   GRANT SELECT ON qws.* TO [username]@localhost IDENTIFIED BY '[password]';

   Replace [username] and [password] with appropriate values.
8. The following QWServer configuration parameters rely on this new slave database:
   • pwdDatabaseHostAddress: This is the address of the machine the slave was set up on. "localhost" will work for the above example.
   • pwdDatabasePortNumber: This should be configured as 3306, unless the MySQL configuration has been changed for this slave.
   • pwdDatabaseIdentifier: This should be configured as "qws"
   • pwdDatabaseUsername: A database user on the local slave, with read permission to the "qws" database. This is the user that was created above.
   • pwdDatabasePassword: The password for the user specified above.
   
   

• Use mysql command line to login:  mysql -u root -D mysql -p
• Enter the password for root user
• Type the SQL command:  show slave status\G
• Look at the column "Seconds_Behind_Master" to see how far behind this slave is.

Note that the Seconds_Behind_Master value will only tell you when the last event occurred on the master that warranted replication on the slave.  That is, it is a poor choice of name for this parameter but can give you some idea of how far off the slave is from the master's changes.

To really know if replication is happening, the administrator of the Master database needs to provide all Slave administrators with the numbers found in the Master_Log_File and Read_Master_Log_Pos parameters.  If these match what is shown by the values in the SHOW SLAVE STATUS command on the slave dbs, then the slaves and master are in sync.

Alternatively, you can look at the date of the relay log file and compare that to the current date:

[mysql@qws1 conf]$ cd /var/lib/mysql
[mysql@qws1 mysql]$ ls
ibdata1      ib_logfile1  mysql       qws                       qws1.gps.caltech.edu.pid  qws1-relay-bin.index  test
ib_logfile0  master.info  mysql.sock  qws1.gps.caltech.edu.err  qws1-relay-bin.000001     relay-log.info
[mysql@qws1 mysql]$ ls -l /var/lib/mysql/relay-log.info
-rw-rw----    1 mysql    mysql          55 Nov 22 13:43 /var/lib/mysql/relay-log.info
[mysql@qws1 mysql]$ date
Tue Nov 22 14:04:55 PST 2005
[mysql@qws1 mysql]$ 

	

     The default configuration for the "standard" QuakeWatch Server distribution is to use a QWRelay feeder.  (The default configuration for the "QWIDS" QuakeWatch Server distribution is to use a QWCorba feeder.)   The following section contains instructions on how to configure a QWServer to use a QDDS feeder (on a Unix platform).

In the 'conf' directory:
  Rename "QWServerConfig.xml" to "QWServerConfig_relay.xml".
  Rename "QWServerConfig_qdds.xml" to "QWServerConfig.xml".

Edit the "conf/QWServerConfig.xml" file and change the 'serverIdName' value to a name that is unique and identifiable.  For example, a QWServer on 'qws1.gps.caltech.edu' could be named "QWS1 Server".

Make the "start"/"stop" scripts executable:
  chmod 755 start*
  chmod 755 stop*

For the QDDS feeder to successfully receive messages, port 2222 must opened for both UDP and TCP traffic (through the firewall).

The default configuration is for the QWServer to listen on port 39977 and the Notification Service (CORBA-event-channel) to listen on port 39988.  If using this configuration then these ports need to be opened for TCP traffic.

The "start" scripts that start up the servers create ".pid" files that contain the process-ID numbers for the processes.  These files are used when terminating the servers via the "stop" scripts.

The "startAll" script is used to start up the servers.  See the 'log' directory for generated log files.

     The servers may be configured to listen on port numbers other than the defaults; for instance, to have the QWServer listen on port 29977 and the Notification Service (CORBA-event-channel) listen on port 29988.  To do this, the "conf/QWServerConfig.xml" file would need to be edited to have "serverPortNum = 29977" and "notifSvcPortNum = 29988", and the "startNotif" script edited to include the command-line parameter "-p=29988", like this:
java -Xms16m -Xmx256m -jar ISTINotifServer.jar -p=29988 -g=1 &

     It is possible to have more than one set of QW servers running on the same machine.  To do this, a separate set of ports needs to be used.  The QW server port numbers can be modified as described above.  To change the port used by the QDDS feeder, the "conf/QDDS.config" file settings "LISTEN PORT TCP:" and "LISTEN PORT UDP:" need to be changed to a different value (i.e. 2322).  Additionally, in the "conf/QDDS_comm.lst" file, the "password" text used in the three hub-configuration lines needs to be different from the "password" text used in the "QDDS.config" for any other QDDS feeder running on the same machine.

Initial Testing:  To check if the QDDS feeder is reaching its hubs, it can be useful to increase the level of QDDS-debug output by editing the "conf/QWServerConfig.xml" file and changing the 'LogFileLevel' attribute in the 'QWFeederMod' element to "All_Msgs".  With that change in place and the QW servers running, "QddsFeeder ("QDDS") alive message" entries should appear in the "log/QDDSFeeder_YYYMMDD.log" file.  Note that the "IOError in getMaxReceived: java.io.FileNotFoundException: qddsdata\save_max_received" message is normal.

• Make sure the Notification Service (CORBA-event-channel) program (via 'startNotif' or 'runNotif.bat') is also running.
  

• When using ports less than 1024, special "root" or "administrator" privileges are usually required.

• Make sure the ports for the QWServer (default 39977) and Notification Service (CORBA-event-channel) (default 39988) are not blocked by a firewall.  This can be tested by running "telnet addr port" on a remote machine, where "addr" is the address of the machine hosting the QuakeWatch servers and "port" is one of the port-number values.  If a server is running at the specified port number and is not blocked then the connection will succeed.
  

• Make sure the host name for the machine running the QuakeWatch servers is operational on the client machine.  Running commands like "ping" or "telnet" on the client machine can help determine this.  If the host name will not work but the IP address will, then running the QuakeWatch servers via the "startAllNum" script (Unix) or "runAllNum.bat" batch file (Windows) may operate better (see the 'publishNumericIPFlag' parameter description for more information).
  

• If the machine running the QuakeWatch servers contains more than one network interface ("multi-homed") then it may be necessary to specify the IP address that the servers should use.  For the QWServer, this is configured via the 'serverHostAddress' parameter.  To configure the Notification Service (CORBA-event-channel) program to run at a specified host address, the "-a=address" parameter is inserted into the launch command for the program (i.e. 'java -Xms16m -Xmx256m -jar ISTINotifServer.jar -g=1 -a="131.215.220.4" &').

Version 2.0  [2019-8-14]

• Modified to use the Product Distribution Layer (PDL) Indexer instead of Quake Data Merge (QDM).
  
• Modified for Java 1.9 compatibility.
  

Version 1.141  [2013-11-15]

• Modified checks to feeder input so only large changes in feeder-data-source message numbers will result in warning-level log messages.
  

Version 1.14  [2013-09-24]

• Modified product converter in PDL feeder so generated 'ProductLink' messages will have 'Version' and 'Action' elements inside the 'ProductLink' element (instead of the parent 'Event' element).
  
• Minor modifications to PDL-feeder module.

Version 1.13  [2013-08-27]

• Added PDL feeder.

Version 1.12  [2010-11-09]

• Modified QWRelayFeeder to address issue where reconnect thread could get 'stuck'.
• Added checking and reporting of status-error messages and time of last data message from feeders.
• Added reporting of time of last data message sent.
• Modified to set system property 'java.awt.headless' to true.
  

Version 1.09  [2010-10-06]

• Improved QWRelayFeeder reconnect-after-disconnect response.
• Modified QWRelayFeeder to log connect-fail messages at debug level, and then at warning level after two minutes with errors have elapsed.
  

Version 1.07  [2010-09-08]

• Modified use of console-output file so a new one is created every 90 days (default) and files older than 3 years (default) are automatically deleted.

Version 1.06  [2010-08-23]

• Fixed queuing/memory-usage issue with 'QWRelayFeeder' processing of cache messages at startup.

Version 1.05  [2010-07-16]

• Improved handling of messages containing characters greater than 127.
• Modified 'QWViaFileFeeder' to always use UTF-8 charset when decoding input data.
• Modified to always reject messages with duplicate feeder-data-source message numbers when 'checkDupFdrSourceFlag' is true (regardless of message payload).
  

Version 1.04  [2010-05-13]

• Created 'QddsQuakeMLFeeder' and 'CubeQuakeMLParser' for QuakeML message-format support.
• Fixed issue where relay-feeder messages with time-generated timestamp in future would result in other messages not being stored in file archive.
  

Version 1.0  [2010-02-04]

• Modified feeder CUBE-format parser to support location-method code 'Z' for ANSS-EQ-XML 'Scope'=="Internal".
• Improved relay-feeder detection and rejection of duplicate "recursive" messages when servers are cross-connected.

Version 0.67Beta  [2009-10-09]

• Fixed bug in CUBE-format feeder-parser where version code on delete message was ignored if message had no text comment.
• Modified QWCorbaOutputter to use QWServer's "serverHostAddress" entry for outputter's CORBA ORB.
• Modified to make use of "serverHostAddress" configuration parameter when "qwServicesAvailFlag" parameter is 'false'.
• Modified QWCorbaFeeder to use QWServer's "serverHostAddress" entry for feeder's CORBA ORB.
• Modified CorbaOutSubscriber to make minor improvements to delivery-failure logic and log outputs.

Version 0.66Beta  [2008-10-20]

• Added QWCorbaOutputter configuration parameter 'subscribeAllDefaultFlag' and changed default QWCorbaOutputter behavior to deliver no messages if no domain/channels are subscribed to.

Version 0.65Beta  [2008-07-22]

• Added "outputters" support and QWCorbaOutputter module.
• Modified QDDS feeder to log "Not enough characters in message" error at "debug" level instead of "warning" level.
• Added averaging to excessive-thread-count detection.
• Added slight delay between tracked-log-message trigger and status report output (to allow multiple "simultaneous" messages to be included in the same report).
• Modified CUBE-format parser to handle numeric strings that have whitespace before a plus sign.
• Added 'CubeToAnssEQXML' and 'CubeToQWXML' test utilities.
• Using updated QWCommon (client-side communications layer) modified to release more CORBA resources when closing connection.

Version 0.64Beta  [2008-03-25]

• Added status report configuration parameters and implementation.
• Added QWServices methods 'getStatusReportTime()' and 'getStatusReportData()'.
• Modified clients manager to allow recovery of username when client connection has timed out but client then reuses connection.

Version 0.62Beta  [2007-09-21]

• Modified processing of incoming message-elements so that whitespace between elements is removed and control characters within elements are encoded to "&##;" strings.
• Fixed bugs in CUBE-message parser where incomplete CUBE-field items could result in 'StringIndexOutOfBoundsException' being thrown.

Version 0.6Beta  [2007-08-15]

• Added support for the dynamic feeder-modules configuration file (via the new 'feederModulesCfgFile' configuration parameter).
• Fixed issue with 'QWViaFileFeeder' where input files that failed parsing could get stuck in the 'process' directory and be processed again and again.
• Modified to wait for feeder stops to complete before exiting program.
• Modified to check for 'MsgSrc'/'MsgIdent' values in ANSS-EQ-XML-format messages (if enabled via new 'checkEQMsgIdentFlag' configuration parameter).
• Minor improvement to CUBE-to-ANSS-EQ-XML-format message parsing (added "CUBE_Code" comments).
• Modified 'CubeAnssEQParser' and 'CubeFormatParser' classes to detect and pass through XML-format messages and to allow spaces in date codes.
• Added 'memorySizeWarnMBytes', 'threadCountWarnMargin', 'notifSvrStatusLogName' and 'notifSvrStatusWarnFlag' configuration parameters.
• Updated OpenORB libraries (to "20061129_isti3" version).

Version 0.59Beta  [2006-09-20]

• Modified to recognize ShakeMap product-translation codes for Global and for ShakeMaps from other networks.
• Updated OpenORB libraries (to "20060309_isti1" version).
• Fixed issue where next "alive" message output by server could be delayed if "alive" message requested by a client.
• Added 'QddsAnssEQ' feeder and support for "feederParserClass" configuration setting for 'QWViaFile' and 'QWCorba' feeders.
• Fixed issue where client-versions update information would remain invalid after versions-info file was inaccessible and then accessible.
• Modified to update the client-versions update information even if the last-modified time for the client-versions-information file is older than the one currently held.
• Added configuration parameters 'msgKeyElement1Name' and 'msgKeyElement2Name'.

Version 0.58Beta  [2005-12-14]

• Updated to include QuakeWatch Web Services enhancements.

Version 0.57Beta  [2005-09-16]

• Fixed bug (introduced in version 0.55Beta) where updated client-versions-information was not detected by a client unless the client was restarted.
• Modified to always generate clients-info log file (instead of only when CORBA QWServices were in use).

Version 0.56Beta  [2005-07-13]

• Modified cached-archive code to avoid thread 'interrupt()' calls that can be problematic under Solaris OS.

Version 0.55Beta  [2005-06-08]

• Modified processing of client-versions-info file to use separate thread and timeout to prevent possibility of client update not being offered because of indefinite file I/O access thread block.

Version 0.54Beta  [2005-04-29]

• Modified to properly recognize duplicate messages when data-message element of incoming message contains no child elements.
• Modified to use feeder-data-source host name and message number to differentiate between received messages.
• Fixed 'QWRelayFeeder' processing of feeder-data-source host name and message number values.
• Added "Notification Service / CORBA-Event-Channel" and "QuakeWatch Messaging System Diagram" sections to manual.

Version 0.52Beta  [2005-04-13]

• Fixed so as to actually discard messages whose source is the feeder's own server.
• Modified to prevent extraneous "Error parsing 'SrcHostMsgID'" messages.
• Fixed processing of "-configFile" parameter when followed by an equals sign.
• Put XML doc and revision history into QWServer manual.

• Added server-statistics log output.
• Added 'clientVInfoPollDelaySecs' configuration item.
• Added support for requesting messages via feeder-data-source information.

Version 0.48Beta  [2004-12-03]

• Added clients-information-tracking log file.
• Added support for redirection of clients to other servers.
• Added login-information file option to QWRelay feeder module.
• Modified to prevent 'QWRelayFeeder' from being able to connect to its own QWServer.
• Added 'maximumMessageSize' configuration parameter.
• Added 'publishNumericIPFlag' configuration parameter.
• Added 'allowObsLoginClientsFlag' configuration parameter.
• Changed to improved start/stop launching scripts.
• Added command-line parameter "--configFile" for specifying the configuration file.
• Added "QuakeWatch Server Administrators Manual".
• Added troubleshooting section to manual.
• Updated OpenORB to version "1.4.0_17Nov2004" (for Java 1.5 support).
• Updated QDDS to version "1.3.3 Level 2004.11.08".

Version 0.47Beta

• Implemented validation of client login username and password.

Version 0.45Beta

• Added 'allowDuplicatesFlag' configuration parameter.
• Added "units" attributes to event messages received via QDDS.
• Updated to QDDS 1.3.2 Level 2004.09.18.

Version 0.43Beta

• Implemented 'QWRelay' and 'QWViaFile' feeder modules.

Version 0.32Beta

• Added support event history persistence via cached archive.
• Added support for alternate-servers list and client-services method.
• Added support for "Quarry" attribute in event messages.

Version 0.25Beta

• Implemented support for resend-requests of messages to clients.
• Added support for the QDDS "Trump" event message-type.
• Improved to perform proper cleanup of resources when shut down.
• Improved internal message handling.
• Added and implemented a new QuakeWatch client/server service method for fetching the server name (defined in the server's configuration file).

Version 0.24Beta

• Initial version of client-to-server login implemented.
• Memory cache of event-messages implemented.
• Log-file management improved (new log file each day; older log files automatically deleted).
• New separate log file that tracks connections to the CORBA-event-channel.

Version 0.23Beta

• Communications improvements made that allow clients to run behind a firewall/NATs without any custom configurations.

Version 0.22Beta

• Fixed QWServer console output problem.
• Updates and improvements to QDDS code.
• Added periodic log of memory usage in QWServer and OpenORB Notification Service (event channel).

Version 0.21Beta

• Implemented patches to OpenORB to fix resource leaks.
• Implemented patch to OpenORB to fix possible null-pointer exception error.
• Implemented improvements to OpenORB Notification Service (event channel) launching program.

Version 0.20Beta

• CORBA messaging package changed from ORBacus to OpenORB.

Version 0.11Beta

• Upgraded version of ORBacus in use for CORBA communications.

Version 0.10Beta

• The server can receive event messages via QDDS, translate them to XML and send them into a CORBA-event-channel.

CISN Display Installation at http://www.cisn.org/software/cisndisplay.html

8/26/2019 - Kevin Frechette, Instrumental Software Technologies, Inc. - info@isti.com