QuakeWatch Connection Parameters





Introduction

     QuakeWatch client programs use a shared "common" module to communicate with a QuakeWatch server.  This module manages the CORBA connection and message handling implementation.  The recommended procedure for creating a new "persistent" client is to extend the 'QWClientBase' or 'QWTrackingClient' class found in the 'QWCommon' library.
     The configuration parameters used to configure the connection are described in the next section.  The standard usage is for the parameters to be specified in a configuration file that resides at a default pathname.  An alternate pathname for the configuration file may be specified by supplying "--configFile" as the first command-line parameter and the pathname for the configuration file as the second command-line parameter to the program.



Connection Parameters

     The following parameters are specified in the "<Settings>" element of an XML-format configuration file for the QuakeWatch client.

serverHostAddress = "hostAddress"
     The host-address specification for the server from which the client 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 client 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 client will receive messages  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.  If this parameter is not specified then the filename will default to an empty string ("").  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
client.  If the client 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 client may instead use a new list fetched from the current host server.

altServersEnabledFlag = true/false
     Set 'true' to enable the
client to switch to an alternate server when a loss of connectivity is detected.  If 'false' then the client 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
client 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 = #.#
     Sets the maximum age (in days) for messages that are fetched from the server
.  The age is measured from the time that the event messages were generated on the server and is specified as a floating-point value (such as 1.5 days).  If no messages have been previously received by the client then this parameter will specify how many days' worth of messages will attempt to be fetched from the server.  If the client is persistently tracking messages (i.e., a client that extends 'QWTrackingClient') and messages have been previously received, then the client will attempt to fetch all messages that it missed, even messages that are older than the age specified by this parameter.
     Setting this item to zero will disable the fetching of messages from the server when the client starts up.  Setting this item to a small value (like 0.000001) will effectively disable the fetching (at startup) of old server messages if none were previously received, while still enabling the fetching of messages sent since last previously-received message (i
f the client is persistently tracking messages).  The default value for this parameter varies with different types of clients.

maxServerAliveSec = ##
     Sets the maximum number of seconds that the client will wait for a server "alive" message before determining that the message has been missed.  The server will transmit one "alive" message every ten seconds.  When server "alive" messages have been missed and the number of seconds elapsed since the last-received server "alive" message exceeds the "Server connection timeout" value, the client will attempt to reestablish its connection to the server.  Setting this item to zero will disable alive-message checking.  If this parameter is not specified then the value will default to 15 seconds.

connTimeoutSec = ##
     Sets the number of seconds that the client will wait, after server "alive" messages have been missed, before attempting to reestablish its connection to the server.  Setting this item to zero will configure the client to never attempt to reestablish its server connection.    If this parameter is not specified then the value will default to 30 seconds.

maxConnRetryWaitMinutes = ##
      
Sets the maximum number of minutes that the client will wait between consecutive attempts to reestablish its connection to its server (or alternate servers).  After each consecutive failed connection attempt, the amount of wait-time before the next attempt will be doubled (which helps to reduce network traffic during lengthy outages).  This item establishes a maximum wait-time.    If this parameter is not specified then the value will default to 5 minutes.

statusCheckIntervalSec = ##
     Sets the numbers of seconds between status-check calls, where the client checks-in to the server to indicate that the client connection is still active.    If this parameter is not specified then the value will default to 60 seconds.

subscribeDomainTypeList = "domain:type,domain:type..."
     Specifies that only messages referencing a domain/type from the given list will be received from the server.  The list string must be in the format "domain:type,domain:type...".  Occurrences of the ':' and ',' characters not meant as separators may be "quoted" by preceding them with the backslash ('\') character.  List items missing the ':' character will be considered to specify only a domain name (allowing all type names to be accepted).    If this parameter is not specified then all messages will be received from the server.


coaFile = "URL-path"
     The location of the "Certificate of Authority" file for the client.  See the "Message Signing Implementation" section for more information.
    
crlFile = "URL-path"
     The location of the "Certificate Revocation List" file for the client.  See the "Message Signing Implementation" section for more information.

processMessageWithoutSigFlag = true/false
     If message signing authentication is configured for the client then this parameter is set 'true' to allow messages without signatures to be accepted; 'false' to reject messages without signatures. 
If message signing authentication is not configured for the client then this parameters is ignored.    If this parameter is not specified then the value will default to 'true'.

clientLogFileName = "logFileName"
     The name of the log file to be written to by the client.  A date code in the form "_yyyymmdd" will be inserted into the name, and a new log file name will be used each day.

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

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

logFilesMaxAgeInDays = ##
     The maximum age, in days, for log files generated by the
client.  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 30 days.

consoleRedirectFileName = "fileName"
     An optional specification for the console output redirect file name.  If this parameter is not specified then the console output will not be redirected.

clientHostAddress = "hostAddress"
     Specifies the local host address to be passed into the client's CORBA implementation.  This parameter usually not used.

clientPortNum = ##
    
Specifies the local port number to be passed into the client's CORBA implementation.  This parameter usually not used.

trackingFileName = "fileName"
    
Specifies the filename used by the QuakeWatch communications module to hold tracking information for the last-received message.  This parameter is only used by clients that extend the 'QWTrackingClient' class found in the 'QWCommon' library (as opposed to the 'QWClientBase' class).  If this parameter is not specified then the value will default to "qwTracking.dat".



QuakeWatch Server Login Information File

The QuakeWatch Server login information file contains the username and password used to validate a connection to a QuakeWatch Server.  The password may be specified in plain text (in which case the password will be replaced with an encrypted version after the first time it is used by the client).  This file is specified via the "loginInfoFileName" parameter.

The first entry in the file is always the username:

username = "yourUser"

The second entry is the password, which may be specified using one of the following:

password = "yourPwd"
stdEncPassword = "yourStdEncPwd"
encryptedPassword = "yourEncyptedPwd"

The 'password' entry specifies the password in plain text.  The first time the login information file is used it will be rewritten with the "password" entry replaced by an 'encryptedPassword' entry containing an encrypted version of the password.

The 'stdEncPassword' entry specifies the password in a "standard" encoded form (using Unix-style "crypt").  The first time the login information file is used it will be rewritten with the "stdEncPassword" entry replaced by an 'encryptedPassword' entry containing an encrypted version of the "standard" encoded password.

The 'encryptedPassword' entry specifies the password in an "encrypted" form.

If more than one type of password entry is given, only one will be used, with the order of precedence as shown above.

The following is a sample login information file:

username = "yourUser"
password = "yourPwd"



Message Signing Implementation

     The QuakeWatch Server may be configured to use certificates and public/private keys to "sign" all of its outgoing messages, allowing connected clients to authenticate the messages.  Below is a summary of terms and algorithms for the implementation.

CA - Certificate Authority - The software and people that build certificates and maintain the CoA and CRL.

CoA - Certificate of Authority - The CA's certificate (root certificate) which the CA uses to sign other certificates and the CRL. Others use the CoA to ensure the certificates and the CRL were signed from the CA.

CRL - Certificate Revocation List - The list of certificates that have been revoked. This is maintained by CA and is updated as needed. The CA signs the CRL using the CoA's private key.

Certificate - contains the user's public key and some information about who they are. The CA signs the certificate using the CoA's private key. Others use it to ensure the message was from the user.

Private/public key - The keys are created by a user and used to obtain a certificate from the CA. The private key is used for signing. The public key (which is contained in the certificate) is used to verify the signature.

Signature - The signature is a unique set of bytes that is used for authentication and integrity assurance of digital data. It is derived from the private key and digital data.

1. The CA provides the following: a) Certificate of Authority (CoA) - stored as a URL. b) Certificate Revocation List (CRL) - stored as a URL.

2. The QWServer provides to clients its own Certificate (stored only as a file). This must match the server's private key.

3. The server puts a signature into "Signature" attribute of the "QWMessage" element. To do this, the server uses its private key. (The signature must match the server's certificate.)

4. The client fetches the CoA and CRL from the CA (via URLs) and the certificate from the server (via a request to the server.) It should: a) Verify the CoA has not expired. b) Verify the CRL has not expired (the update time is not after the current time and the next update time if supplied is not before the current time) and is from the CA. c) Verify the server's certificate has not expired, is from the CA and is not on the CRL.

5. The client then verifies that the message contains a signature that was signed by the server's (valid) certificate.  If the signature is not valid then the client will reject the message.




'QWClientBase' and 'QWTrackingClient' Classes

     QuakeWatch client programs may be created using Java by extending the 'QWClientBase' class in the QWCommon library.  The code in 'QWClientBase' implements the details of server connection and message handling.  The client program implements a call-back to process the incoming messages (via the 'QWDataMsgProcessor' interface).  The 'QWConOutClient' program is an example of this type of client.
     The 'QWTrackingClient' class (in the QWCommon library) enhances 'QWClientBase' by using a tracking file to hold information about the last-received message.  As such, client programs created by extending the 'QWTrackingClient' class will "remember" the last-received message before shutdown and request any missed messages after being restarted.  The client program implements a call-back to process the incoming messages (via 'MsgProcessorInterface').  The 'QWFileOutClient' program is an example of this type of client.


10/19/2006 - Eric Thomas, Instrumental Software Technologies, Inc. - info@isti.com