Earthquake Information Distribution System (EIDS)

Last Updated February 9, 2009


Contents


Contacts


Introduction

The Earthquake Information Distribution System (EIDS) replaces the Quake Data Distribution System (QDDS) for distributing earthquake data over the Internet.

Like QDDS, the system is written entirely in Java which makes it platform independent. It has been tested on Solaris, Windows, and Linux platforms. EIDS is developed and maintained by Instrumental Software Technologies, Inc, (ISTI).


Differences between EIDS and QDDS

Summarized from ISTI's QWIDS - EIDS Summary Document

Data Providers and Data Recipients

Unlike QDDS, EIDS separates the Data Provider and Data Recipient roles. As the names suggest, a Provider sends messages and a Recipient receives messages. Some users may be both Providers and Recipients.

In EIDS, a Data Provider runs a Server to publish messages and a Data Recipient runs a Client to receive messages. Users who are both Providers and Recipients must run both a Server and a Client. Clients connect to a Server and establish a persistent connection. Once the connection is established, the Server "pushes" messages to the Client.

EIDS Hubs are Clients of Data Providers, and Servers for Data Recipients. EIDS Hub configuration controls which Data Providers can publish messages.

Firewalls

By default, Servers listen to TCP ports 39977 and 39988. Because connections are initiated by the client (on the client machine), most client-machine firewalls do not require configuration. Clients do not use a specific source-port when connecting to servers.

Messages

EIDS accepts any well-formed XML message. EIDS Earthquake messages use the ANSS EQXML format. For compatibility with QDDS and CUBE, EIDS automatically converts CUBE messages to and from EQXML.

There are no inherent message size limitations, although hubs reject any message larger than 512Kb.


System Requirements


EIDS Installer

The EIDS Installer guides the installation and configuration process and is sufficient for most uses. Configuration files and other paths may differ from the standard ISTI EIDS/QWIDS Distribution and Documentation. All paths in configuration files generated by the EIDS Installer are relative to the base EIDS install directory.

Usage

The installer is packaged as a standard java archive (JAR) file. The usage is displayed when the installer is run with no arguments.

java -jar EIDSInstaller.jar (--install|--update) [--cubeClient] [--xmlClient] [--server] [directory]

Installing an EIDS CUBE Client

The QWCubeOutClient outputs CUBE messages and provides a seamless replacement for QDDS Data Recipients that need to RECEIVE messages. For those familiar with EIDS, any EQXML messages are converted to CUBE before output. All other messages are delivered as normal.

java -jar EIDSInstaller.jar --install --cubeClient

The installer prompts for primary server address and port number, and optionally allows an unlimited number of backup servers. If a client is unable to connect to the primary server, backup servers are tried in the order they are entered.

ISTI QWCubeOutClient Documentation.

Installed Files

Running the CUBE Client Manually

Using the Unix Init or Windows Batch scripts instead is recommended.
On Windows forward slashes (/) should be replaced with back slashes (\).

cd EIDS_INSTALL_DIR
java -jar bin/QWCubeOutClient.jar --configFile conf/cubeClient.xml

Installing an EIDS EQXML Client

The QWFileOutClient outputs EQXML messages and has no QDDS equivalent. Event messages use the ANSS EQXML XML format. All other messages are delivered as normal.

java -jar EIDSInstaller.jar --install --xmlClient

The installer prompts for primary server address and port number, and optionally allows an unlimited number of backup servers. If a client is unable to connect to the primary server, backup servers are tried in the order they are entered.

ISTI QWFileOutClient Documentation.

Installed Files

Running the EQXML Client Manually

Using the Unix Init or Windows Batch scripts instead is recommended.
On Windows, forward slashes (/) should be replaced with back slashes (\).

cd EIDS_INSTALL_DIR
java -jar bin/QWFileOutClient.jar --configFile conf/eqxmlClient.xml

Installing an EIDS Server

The IstiNotifServer and QWServer send messages to EIDS hubs and are intended to be a seamless replacement for QDDS Data Providers that need to SEND messages. The server is configured to accept either CUBE or EQXML messages, from the directory polldir, along with any other well-formed XML message. ISTI QWServer Documentation.

java -jar EIDSInstaller.jar --install --server

The installer prompts for the server address, server and notification server port numbers, server name, and feeder name. The installer also optionally configures Relay Feeders. A Relay Feeder acts as a client to another Server, and re-publishes the other Server's messages for this Server's clients.

A redundant, multi-master group of servers can be set up by configuring each server with a Relay Feeder for each other server in the group. In this configuration, a message only needs to be submitted to one of the servers and it will be available on all servers.

Running an EIDS Server in a NAT environment.

This only applies when the internal IP address/hostname and public IP address/hostname differ.

You will need an external host name (public DNS name), which forwards connections on TCP ports 39977 and 39988 to your server.

After these changes, restart your server. If all is well, you should see something like this in the EIDS Server log (log/server_YYYYMMDD.log):

Server successfully started

Installed Files

Running the Server Manually

Using the Unix Init or Windows Batch scripts instead is recommended.
On Windows, forward slashes (/) should be replaced with back slashes (\).

The Notification Server should be running when the server starts. The server will attempt to connect to the notification server for 15 seconds before shutting down.

cd EIDS_INSTALL_DIR
java -jar bin/ISTINotifServer.jar -n -p 39988 &
java -jar bin/QWServer.jar --configFile conf/server.xml

Unix Init Scripts

Unix init scripts are installed automatically when the installer is run on a non-Windows system. This script can be used to start, stop, and check the status of EIDS processes manually or automatically. The created scripts can be moved from EIDS_INSTALL_DIR, but will NOT work if EIDS_INSTALL_DIR is moved or renamed.

Requirements for using Unix Init Scripts

These scripts have been tested on RedHat Enterprise Linux 4+, Solaris 7+, and Mac OS X 10.4+. It may be possible to run these scripts on other systems.

Usage

The init script takes one of the following arguments

Installing a Crontab Entry

Calling the init script from the crontab will automatically start, or restart if the process isn't running, the EIDS applications.

This example assumes the crontab runs in bourne shell (sh) or bash. If you use a different shell for your crontab, the example is still relevant but stream redirection (>/dev/null 2>&1) may differ.

# start (if not already running) every five minutes
*/5 * * * * EIDS_INSTALL_DIR/XXXXX_init.sh start >/dev/null 2>&1 &

Installing as a Linux Service

Installing EIDS as a Service automatically starts the applications on system startup. This example is tailored for RedHat Enterprise Linux.

chkconfig Init Script Wrapper

#!/bin/bash
#
# chkconfig: 345 90 10
# description: EIDS Init Script
#
# see http://kbase.redhat.com/faq/FAQ_52_5733.shtm for more information
#

## init script being wrapped
INIT_SCRIPT="EIDS_INSTALL_DIR/XXXXX_init.sh"

if [ $# -lt 1 ]; then
	echo "Usage: $0 {start|stop|restart|status}"
	exit 1
fi

_ACTION=$1
# run script and store exit status
$INIT_SCRIPT $@
_EXIT_STATUS=$?
# on RHEL, chkconfig uses a lock file in this directory
_SERVICE_LOCK_DIR="/var/lock/subsys"
# chkconfig service and lock file name based on script name
_SERVICE_NAME=`basename $0`
case "${_ACTION}" in
	start)
		if [ ${_EXIT_STATUS} = 0 ]; then
			#only create lock if service running
			touch "${_SERVICE_LOCK_DIR}/${_SERVICE_NAME}"
		fi
		;;
	stop)
		if [ ${_EXIT_STATUS} = 0 ]; then
			#only remove lock if service not running
			rm -f "${_SERVICE_LOCK_DIR}/${_SERVICE_NAME}"
		fi
		;;
esac

#pass init script exit status
exit ${_EXIT_STATUS}

Adding and Starting Service

For this example, assume the above script is 1) copied into a file named eidsCubeClient, and 2) EIDS_INSTALL_DIR/XXXXX_init.sh is replaced with the appropriate path.

#become super user
su -

#install chkconfig wrapper script
cp eidsCubeClient /etc/init.d/.

#add service
chkconfig --add eidsCubeClient

#start service
service eidsCubeClient start

Windows Batch Files

Windows batch files are installed automatically when the installer is run on a Windows system. These batch files can be used to launch the installed EIDS applications(s). The batch file(s) can be moved from EIDS_INSTALL_DIR, but will NOT work if EIDS_INSTALL_DIR is moved or renamed.

Double-click the batch file, or run the following command in a command prompt:

EIDS_INSTALL_DIR\XXXXX_run.bat

Using the EIDS Client

Check if the Client is Running


Using the EIDS Server

Send a Message

Move a file into the directory EIDS_INSTALL_DIR/polldir. Files should be moved instead of copied, otherwise a file may only be partially written when EIDS tries to read it.

	mv MESSAGE_TO_SEND EIDS_INSTALL_DIR/polldir/.

Check if a Message was Sent

If the message was sent via a servers EIDS_INSTALL_DIR/polldir, it should appear in the EIDS_INSTALL_DIR/oldinput directory.

	grep EVENTCODE EIDS_INSTALL_DIR/oldinput/*

Check if a Message was Received

If the message was received (locally OR from another server) it should appear in the EIDS_INSTALL_DIR/storage directory. There is one file per day in the EIDS_INSTALL_DIR/storage directory, and each message is one line in one of these files.

	grep EVENTCODE EIDS_INSTALL_DIR/storage/QWEvents*

Check Currently Connected Clients

Currently connected clients are logged to the EIDS_INSTALL_DIR/log/QWServerClientsInfo_YYYYMMDD.log log file, where YYYYMMDD is the date the file was created. The list of currently connected clients is output every 10 minutes. The log uses this format:

Jan 22 2009 23:27:13:  
  Currently connected clients (7):
    1. user="", name="QWFileOutClient", IP="136.177.24.123", host="gldeids", startTime="Jan 22 2009 17:55:56 UTC", ver="1.3", authIP="136.177.24.123", authHost="gldeids", commVer="1.2", openORBver="1.4.0_20061129_isti3", OS="Linux", javaVer="1.5.0_09", connTime=5:31:03, lastCheckIn="Jan 22 2009 23:27:05 UTC"
    2. user="", name="QWRelayFeeder", IP="137.227.224.89", host="eids1", startTime="Jan 06 2009 15:41:19 UTC", ver="1.5", authIP="137.227.224.89", authHost="eids1", commVer="1.3", distrib="QWRelay_default", openORBver="1.4.0_20061129_isti3", OS="Linux", javaVer="1.5.0_11", connTime=5:30:04, lastCheckIn="Jan 22 2009 23:26:50 UTC"
    ...
Jan 22 2009 23:27:13:  

Check if the Server is Running