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.
To install History Listener, please refer to the Installation section of Chapter 1 of this guide.
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.
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
Option | Description |
---|---|
--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. |
The History Listener has a very simple configuration file. The following table details the available options.
Table 3-2. History Listener Configuration File Options
Option | Description |
---|---|
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 |
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 "./". |
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 |
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.
The controls in this tab are described in the following listing.
Table 3-3. General Configuration Options
Option | Description |
---|---|
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.
Table 3-4. Network Configuration Options
Option | Description |
---|---|
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. |