help | logout
History Listener

Chapter 3. History Listener

The RSP History Listener tool is a convenient, efficient and scalable customized database designed specifically for RSP history data (gathered by the RSPD daemons). This program runs unobtrusively in the background on any host across a network, accepting connections from the RSPD nodes. Each node automatically updates the History Listener on its current status, so an up-to-date copy of a host's system data is always available.

Although RSPD allows for history saving through MySQL, only the History Listener combines the efficient LZW compression algorithm with easy remote access in a simple package. For these reasons the History Listener is recommended as the preferred history archiving mechanism (though using MySQL will not impede on functionality - only ease of use and/or efficiency).

Once a History Listener program is running, and RSP nodes are sending their system data to be archived to it, RSP Web can be utilized to access this data. The History Listener, upon accepting a certain set of criteria (including a range of dates, host and module keys), will search through each of the files it has been archiving for the appropriate data. The History Listener contains built-in mechanisms to flush or rotate old logs. After a specified period of time, old logs can be deleted, or if desired rotated and moved for archival and future access. To expedite searches, data is indexes based on host, module and key, to minimize the time needed to retrieve sets of data.

Implementing a History Listener on a network is very simple. Designed to be a drop-in replacement for other database programs, such as MySQL, the History Listener takes no more then a couple of minutes to setup and have running.

Installation

To install History Listener, please refer to the Installation section of Chapter 1 of this guide.

Configuration

The History Listener has a number of configurable options. On non-Windows systems, these options can be specified either at application start (via the command line) or through a configuration file (which eliminates the need for lengthy commands every time the History Listener is to be started). There also exist a number of options that cannot be specified through command line options. For this reason, a configuration file is always required in order to start the History Listener. On Windows systems, there are no command line options. Although the configuration file still exists (and be editted just as on Linux/UNIX ystems), there exists a GUI interface for all options. Therefore non-Windows users should refer to the "Command Line Options" and "General Configuration File Options" sections, while Windows users should refer to the "Configuration in Windows" section.

Command Line Options

The following command-line options are available to the History Listener, which (except in the case of the "--help" method) affect the behavior of the program during execution.

Table 3-1. History Listener Command Line Options

OptionDescription
--help (-h) Prints a help message and exits.
--debug (-d) Prevents History Listener from forking to the background (which is the default). Also displays all log messages to the console while running.
--config {file} Specifies the location to read a configuration file from. Must be followed by a space and then the location of a configuration file.
--syslog (-s) Sends all log messages to the syslog daemon instead of writing messages to a History Listener log file.
--logfile (-l) {file} Specifies where all log messages should be saved.
--port (-p) {port} Overrides the default port (3499) for communications and instead uses the specified port.

Configuration File Options

The History Listener has a very simple configuration file. The following table details the available options.

Table 3-2. History Listener Configuration File Options

OptionDescription
syslog Specifies whether syslog should be used for logging messages. Possible options are "true" or "1" if syslog should be used, and "false" or "0" if not. The default is to not use syslog.
logFile Indicates the location where the file of log messages should be stored, if syslog is not used. The default is the current directory, named ./historyListener.log.
verbose Specifies which levels of log messages should be written to the log file. Two options exist: (1) normal, and (2) loud. The "normal" value prints only error messages, while "loud" prints both warning and error messages.
port Specifies the port on which History Listener should listen for incoming connections (from a viewer program). The default is 3497.
timeout Indicates the number of seconds that should be waited before declaring a connection "broken". Slower networks/machines may require this to be a higher value. The default is 5 seconds.
checkForUpdates The RSP checkForUpdates feature is designed to alert you to when new versions of the RSP software are available. There are two times it checks: every 48 hours, and when the History Listener is first run. If there is a new update, the History Listener will log a message to the History Listener log file. A value of "true" will enable these checks.
maxConnections Specifies the total number of viewer connections allowed at a given time. The default is 5.
allowAutoDiscover If set to true, other applications will be able to find this History Listener. Periodically sends out a "HERE I AM" message with the IP address and port of this system. The default value is true.
adMCastGroup Indicates to the HistoryListener the multicast group that should be used for the Auto Discover functionality. This only applies if allowAutoDiscover is set to true. The default is 225.0.0.37.
adMCastPort Specifies the multicast port this History Listener should use to send Auto Discover packets. Like adMCastGroup, this option only applies if the allowAutoDiscover option is set to true. The default is 3498.
allowSSL Allows connecting monitors to use secure SSL communication. Values are 1 or 0. Default setting is on.
sslCertificateDir Only valid on non-Windows systems. Specifies an alternate directory for SSL certificates. The default location is /etc/rsp/ssl.
block/allow These two options are each lists. Therefore, they can be set to multiple values. Each value can be all or part of an IP address (using wildcards). Also, the word "all" can be used to indicate all addresses. An example may be

   block = all
   allow = 10.0.1.*
   allow = 192.168.0.31

historySavePath Specifies where to save the database and index files while they are being actively used. Default is "./".
flushHistoryDays Specifies the number of days after which the database should be flushed (or rotated if rotateHistory is set). The start time is based on when the database file was first created. The default is 14 days.
rotateHistory This option can be "1" or "true" if set, and "0" or "false" if off. It specifies if after the flush time period (set with flushHistoryDays) the database and index file should be renamed based on the current date, thereby letting them be archived for future use. If set to "0", the files will be flushed and new ones created. Default is false.
rotateTime Indicates the time at which logs should be rotated/flushed. Each day at this time, as well as at startup, History Listener will check if the database is older than the number of days set by flushHistoryDays, and then will rotate/flush accordingly. The time is simply the hour (in military time 0-23) and the minute, separated by a colon (':'). Examples are "04:00" and "23:15". The default is midnight, "0:00".
rotatedDir If rotateHistory is set to true, then this option specifies where rotated database and index files should be moved to. The default is "./".

Configuration File Examples

The following listing details a complete historyListener.conf file, which is needed by the History Listener to specify behavior (as many of these options cannot be specified via command-line options).

# historyListener.conf

verbose = normal
port = 3496
timeout = 5

# Block/Allow data
block = all
allow = 127.0.0.1
allow = 192.168.0.*
allow = 10.0.1.*

historySavePath = ./

# Rotate old files every 14 days
flushHistoryDays = 14
rotateHistory = 1
rotateTime = 4:00
rotatedDir = /var/log/hl
			

Configuration in Windows

Although Windows users are welcome to edit configuration files, the simpler way of doing things is to graphically configure the History Listener with the Configuration dialog box. It is accessed by starting up History Listener and either double clicking on its icon in the taskbar, or right clicking on the icon and selecting the "Configure..." menu item.

This dialog box is organized into two tabs. The first tab is the "General" tab and is displayed in Figure 1.

Figure 3-1. History Listener "General" Tab

The controls in this tab are described in the following listing.

Table 3-3. General Configuration Options

OptionDescription
Log File Verbosity Specifies which levels of log messages should be written to the log file. Three options exist: (1) quiet, (2) normal, and (3) loud. The "quiet" value prints only error messages, "normal" prints both warning and error messages, and "loud" prints all log messages.
Log File Location Indicates the location where the file of log messages should be stored. The default is the current directory, named historyListener.log.
Save Folder Specifies where to save the database and index files while they are being actively used. Default is "./".
Flush History Every ___ Days Specifies the number of days after which the database should be flushed (or rotated if rotateHistory is set). The start time is based on when the database file was first created. The default is 14 days.
Rotate/Flush Time Indicates the time at which logs should be rotated/flushed. Each day at this time, as well as at startup, History Listener will check if the database is older than the number of days set by flushHistoryDays, and then will rotate/flush accordingly. The time is simply the hour (in military time 0-23) and the minute. Examples are "04:00" and "23:15". The default is midnight, "0:00".
Rotate Old History Files This option specifies if after the flush time period the database and index file should be renamed based on the current date, thereby letting them be archived for future use. If set to off, the files will be flushed and new ones created. Default is off.
Rotate Files To If Rotate Old History Files is set to true, then this option specifies where rotated database and index files should be moved to. The default is "./".
Check For Updates The RSP Check For Updates feature is designed to alert you to when new versions of the RSP software are available. There are two times it checks: every 48 hours, and when the History Listener is first run. If there is a new update, the History Listener will log a message to the History Listener log file.

The second tab is "Network", which allows the user to configure settings related to incoming monitor connections.

Figure 3-2. History Listener "Network" Tab

Table 3-4. Network Configuration Options

OptionDescription
Timeout Indicates the number of seconds that should be waited before declaring a connection "broken." Slower networks/machines may require this to be a higher value. The default is 5 seconds.
Maximum Connections Specifies the total number of monitor connections allowed at a given time. The default is 5.
Listener Port Specifies the port on which the History Listener should listen for incoming connections (from a viewer program). The default is 3497.
Allow SSL Connections Allows connecting monitors to use secure SSL communication.
Allow Discovery If turned on, other applications will be able to find this History Listener. Periodically sends out a "HERE I AM" message with the IP address and port of this system. The default value is true.
Multicast Group Indicates to History Listener the multicast group that should be used for the Auto Discover functionality. This only applies if AutoDiscover is allowed. The default is 225.0.0.37.
Multicast Port Specifies the multicast port this History Listener should use to send Auto Discover packets. Like "Multicast Group", this option only applies if Discovery is allowed. The default is 3498.
Blocked/Allowed The "Blocked" and "Allowed" entries are lists of IP addresses or IP address ranges which should be allowed or disallowed access. IP ranges are given with asterixes. So "127.0.0.1", "10.*", or "192.168.0.*" would all be acceptable. The word "all" is also acceptable. A common practice is to block all connections by default, and then only allow certain known IP ranges. Such is the case in the figure above.