======================================================================
Halcyon PrimeAlert (R) Neuron Agent for Microsoft Windows
Version 3.1.0
README
======================================================================
Readme Contents
===============
* Readme Contents
* Included Components
* Acknowledgements
* Definitions
* Informational Text Files
* Installation and Uninstallation Instructions
* Troubleshooting
* Overview
* Using the Neuron Agent for Microsoft Windows
* Integrating the Neuron Agent with Third Party Frameworks
* License
* Contact Information
Included Components
===================
This distribution includes the following Halcyon products:
PrimeAlert Neuron Agent for Microsoft Windows
PrimeAlert SystemAlert for Microsoft Windows
PrimeAlert MIB-II System
PrimeAlert Agent Statistics
PrimeAlert EventLogAlert
PrimeAlert WebAgent
PrimeAlert ProcessMonitor
PrimeAlert ScriptRunner
PrimeAlert LogFileMonitor
PrimeAlert Reporter (Agent Component)
Acknowledgements
================
PrimeAlert Reporter uses RRDTool software developed by Tobi Oetiker
(http://tobi.oetiker.ch/hp/). Reporter runs RRDTool as a separate
executable, and is only loosely coupled with it. The original and
modified source code for RRDTool are included in this distribution,
which can be found in the compressed file:
\install\sbin\src\rrdtool-1.0.20-modified-src.tar.Z
There is no need to download RRDTool separately.
RRDTool is covered under the terms of the GNU General Public License,
Version 2, June 1991 (http://www.gnu.org/licenses/gpl-2.0.html).
PrimeAlert Reporter uses japach, developed by Jirka Kosina
(http://www.jikos.cz/jikos/japach/). Reporter runs japach as a
separate executable, and is only loosely coupled with it.
The original and modified source code for japach are included in this
distribution, which can be found in the compressed file:
\install\sbin\src\japach-0.4.8_mod-HALReporter.tar.bz2
There is no need to download japach separately.
japach is covered under the terms of the GNU General Public License,
Version 2, June 1991 (http://www.gnu.org/licenses/gpl-2.0.html).
A copy of the GNU General Public License Version 2 is included with
this distribution.
Definitions
===========
: On a Microsoft Windows host, the user-selected
installation directory for the Neuron Agent for
Microsoft Windows. The default value is:
C:\Program Files\Halcyon\Neuron.
Informational Text Files
========================
A number of useful informational text files are included with this
distribution:
- README.txt
- INSTALL.txt
- TroubleShooting.txt
- ReleaseNotes.txt
- License.txt
- COPYRIGHT.txt
- GPL.txt
These files are located after installation in the directory:
\docs\HALNeuronWindows
Installation and Uninstallation Instructions
============================================
For installation or uninstallation instructions, refer to the file
INSTALL.txt (see the above section 'Informational Text Files').
Troubleshooting
===============
For troubleshooting information, refer to the TroubleShooting.txt file
(see the above section 'Informational Text Files').
Overview
========
The Neuron Agent for Microsoft Windows monitors the health and statistics
of a host running Microsoft Windows NT 4 or Windows 2003. The agent has
been verified to run on Microsoft Windows NT 4 and Windows 2003.
In standalone mode, the Neuron Agent can send SNMP traps to a
third party trap manager when alarm conditions occur. It can also
execute custom commands in response to alarm conditions, and can
be polled for data using SNMP.
The following modules are provided with this release:
- PrimeAlert SystemAlert for Microsoft Windows
- PrimeAlert MIB-II System
- PrimeAlert Agent Statistics
- PrimeAlert EventLogAlert
- PrimeAlert WebAgent
- PrimeAlert ProcessMonitor
- PrimeAlert ScriptRunner
- PrimeAlert LogFileMonitor
- PrimeAlert Reporter
All four modules are loaded by default when the Neuron Agent for
Microsoft Windows is first started. These modules are described briefly below:
PrimeAlert SystemAlert for Microsoft Windows
--------------------------------------------
This module monitors key system resources of the Microsoft Windows host.
Monitored resources include:
- Processors
- Logical and physical disks
- Real and virtual memory
- Operating system objects (processes, threads, handles, etc.)
Note: To enable the Disk I/O Statistics, run 'diskperf -ye' and reboot.
PrimeAlert MIB-II System
------------------------
PrimeAlert MIB-II System provides information about the MIB used by the
Neuron Agent for Microsoft Windows.
PrimeAlert Agent Statistics
---------------------------
This module monitors statistics about the internal state of the agent
and of the agent process.
Note: If the Memory Usage and Virtual Memory Size values exceed the
Critical alarm thresholds (default is set to 70000 Kb for Virtual
Memory Usage), the agent will exit automatically.
PrimeAlert EventLogAlert
------------------------
This module monitors the Microsoft Windows event logs. This module may be loaded
three times, once for each event log (System, Security, and
Application).
When the module is loaded, a program named evdump is spawned and writes
any new events to a log file located in \local\log. The
module then monitors this log file. The evdump program is killed if the
module is unloaded or disabled.
PrimeAlert WebAgent
-------------------
PrimeAlert WebAgent provides a web-based user interface to configure
and monitor a Neuron Agent. Using a web browser, the WebAgent
allows you to view system status, as well as configure monitoring
modules, alarm thresholds, and alarm actions.
PrimeAlert ProcessMonitor
-------------------------
PrimeAlert ProcessMonitor allows the monitoring of a process or
groups of processes running on an agent host system. It is possible
to define process matching criteria to determine the processes to
be monitored.
PrimeAlert ScriptRunner
-----------------------
PrimeAlert ScriptRunner can be used to schedule the execution of
user-written scripts using sophisticated periodic expressions.
Furthermore, the output of the scripts executed via PrimeAlert
ScriptRunner can be scanned for error messages that match a
user-specified pattern.
PrimeAlert LogFileMonitor
-------------------------
PrimeAlert LogFileMonitor can be used to scan a single local file
or a series of local files for user-specified patterns. Multiple
files (or multiple series of files) may be scanned by loading
multiple instances of the module.
PrimeAlert Reporter
-------------------
PrimeAlert Reporter maintains a database of historical values for
monitored objects. User can view the stored data as a graph or
a list. Stored data can be exported into standard file formats
that are compatible with spreadsheet.
Using the Neuron Agent for Microsoft Windows
============================================
Starting the Agent
------------------
You can choose to start the Neuron Agent during installation.
Since the agent is a service, it can also be controlled via the
Services applet in the Microsoft Windows Control Panel. The service
name is "Halcyon PrimeAlert Agent". That is also where you can
specify a different user/password for the service.
Configuring the SNMP Port
-------------------------
Typically, configuration of the Neuron Agent for Microsoft Windows
is done during installation. If you would like to change the SNMP
port used by the agent after installation, edit the text file
\local\cfg\domain-config.x. This file will contain
a section labeled "agent" like this:
agent = {
snmpPort = 6681
}
To change the SNMP port, simply change the number to the desired port
number, and restart the agent service.
Integrating the Neuron Agent with Third Party Frameworks
=========================================================
The standalone Neuron Agent includes several features that
facilitate integration with a third-party management framework, without
the need for a PrimeAlert Server. Managers can access module
data via SNMP, and can be notified of events via SNMP traps or custom
scripts.
Agent Events
------------
The agent can send SNMP traps to one or more SNMP managers when an
event occurs. Custom scripts can also be executed for each event,
for example, to send an e-mail when an alarm condition exists.
There are several types of event:
- Agent coldstart ("S")
This event occurs when the Neuron agent starts execution. Note
that any open alarms (see below) are no longer relevant after an agent
coldstart event is triggered and "close" events will not be issued
for these alarms.
- Alarm open ("O")
An alarm condition exists. This is the most common type of event,
and occurs when an alarm rule has been satisfied. For example,
an alarm may be triggered when a pre-defined threshold is exceeded
(for example, memory usage > 90 %).
- Alarm close ("C")
An alarm condition has ended.
- Log event ("L")
Log events typically occur when an error is detected by a module,
but the nature of the error is such that it is not a condition
which "starts" or "ends", but is simply an occurrence which needs
to be reported. For example, an error message printed to a log
file might cause a log event.
- Alarm acknowledge/unacknowledge ("A"/"N")
This event is triggered when an alarm condition is acknowledged
by an operator. This type of event does not normally occur in a
standalone agent.
- Module unavailable ("U")
This event is triggered when a module is unloaded or disabled by
an operator, and also when a module goes into a "down" state.
A module will typically go into a down state when it is not
capable of performing its intended function, for example the
PrimeAlert LogFileMonitor module will go into a down state if
the target log file does not exist. The purpose of this event
is to signal that any open alarms on a module are no longer
relevant - "close" events will not be issued for these alarms.
SNMP Trap Format
----------------
The Neuron Agent sends SNMP traps using a private trap format.
The MIB describing this format is installed in the following
location:
\install\cfg\HALEventTarget-trap.mib
Adding/Editing a Trap Target
----------------------------
During installation, there is an option to configure the agent to send
SNMP traps to a remote host. If this host needs to be changed after the
product is installed, or if you would like the agent to send traps to
an additional host, a configuration file needs to be modified and the
agent restarted. The configuration file is located at:
\local\cfg\HALEventTarget-config.x
Care must be taken when modifying this file. In particular, the file
contains three "blocks" called "params", "target" and "info". The
"target" block should not be changed. The "params" block only needs to
be changed if you are using a custom script to process events. The "info"
block contains one entry for each SNMP manager host receiving traps.
To change the hostname or port of the machine currently setup to receive
traps, look for a block named "MgrTrap" inside the "info" block. If
there is more than one host receiving traps, find the entry for that
host:
info = {
MgrTrap = {
host = oldhostname
port = 162
tags = event
params = SnmpTrap
}
}
and update the values of the "host" and/or "port" tags to point to the
new machine:
info = {
MgrTrap = {
host = newhostname
port = 1234
tags = event
params = SnmpTrap
}
}
To add an additional host to the list of trap targets, simply add another
block inside the "info" block:
info = {
MgrTrap = {
host = hostname_one
port = 162
tags = event
params = SnmpTrap
}
MgrTrap2 = {
host = hostname_two
port = 162
tags = event
params = SnmpTrap
}
}
The names of the blocks are irrelevant, but they must be unique, and must
not contain any "special" characters (punctuation or control characters).
There is no limit to the number of trap targets you can add.
For the new configuration to take effect, the agent service must be
restarted.
Processing Events with a Script
-------------------------------
Sending an SNMP trap is just one way the agent can handle an event. It is
possible to execute a user-created script which can do just about anything
with the event information. For example, the script could add a row to a
database table, or send an e-mail. The only restriction is that the script
should execute in timely manner, because a subsequent event will not be
processed until the script terminates. Also note that if the script writes
anything to standard error, the agent will consider the script to have
failed, and the script will run again at a later time.
Event information is provided to the script via command-line arguments.
The arguments are of the form "-name value". These arguments can be
parsed and set into shell variables for easy access with the following DOS
commands:
:start
if "%1" == "" goto end
if "%1" == "-targetHost" set targetHost=%2
if "%1" == "-targetPort" set targetPort=%2
if "%1" == "-ttyp" set ttyp=%2
if "%1" == "-module" set module=%2
if "%1" == "-context" set context=%2
if "%1" == "-description" set description=%2
if "%1" == "-open_time" set open_time=%2
if "%1" == "-close_time" set close_time=%2
if "%1" == "-severity" set severity=%2
if "%1" == "-url" set url=%2
if "%1" == "-scheme" set scheme=%2
if "%1" == "-path" set x_path=%2
if "%1" == "-hostname" set hostname=%2
if "%1" == "-ip" set ip=%2
if "%1" == "-port" set port=%2
shift
shift
goto start
:end
These are the parameters:
hostname - Hostname of the agent host
ip - IP address of the agent host
port - SNMP port of the agent
ttyp - Event type. Possible values are:
"O" - Open alarm
"C" - Close alarm
"L" - Log alarm
"A" - Alarm acknowledge
"S" - Agent coldstart
"U" - Module unavailable
module - The module that created the event
Example: "HALLogFileAlert"
context - The instance (if applicable) of the module that
created the event
url - URL which identifies the source of the alarm
Example: (broken into two lines for readability)
"snmp://192.168.12.40:1161/mod/HALCEMF/cemfcore/processes/
processTable/processEntry/restarts#DiscoveryScheduler/"
path - The path component of the above URL
Example: "mod/HALCEMF/.../restarts"
description - Text message described the alarm
Example: "PrimeAlert CEMF Monitoring DialogMgrServer
Process State is not running"
open_time - The time that the alarm condition began
Example: "Aug 29, 2002 19:10:17.000 GMT"
close_time - The time that the alarm condition ended
Example: "Aug 29, 2002 19:15:02.000 GMT"
severity - The severity of the event. Possible values are:
"error"
"warning"
"caution"
"disabled"
"off"
"down"
targetHost - This parameter is not part of the event itself, but contains
the value of the "host" tag in the "info" block of the
HALEventTarget-config.x configuration file. The purpose of
this tag is to allow a single script to send events to
multiple targets, by passing the target information on the
command line rather than hardcoding it into the script.
targetPort - Contains the value of the "port" tag in the "info" block of
the HALEventTarget-config.x file.
After the script is created, it should be placed in \local\bin.
Now that the script is finished, the agent configuration must be modified to
use it. Edit the file \local\cfg\HALEventTarget-config.x.
Add a new block inside "params" for the script. There should be one entry
inside "params" for each script, including HALEventTarget-trap. The name of
the block is irrelevant, so long as it contains no special characters.
Suppose the following snippet is the params block of our configuration file,
and we want to add a script called send_email.cmd:
params = {
SnmpTrap = {
type = "script"
secModel = "-"
secName = "-"
secPassword = "-"
secLevel = "-"
scriptName = "HALEventTarget-trap"
}
}
The result should look like this:
params = {
SnmpTrap = {
type = "script"
secModel = "-"
secName = "-"
secPassword = "-"
secLevel = "-"
scriptName = "HALEventTarget-trap"
}
SendEmail = {
type = "script"
secModel = "-"
secName = "-"
secPassword = "-"
secLevel = "-"
scriptName = "send_email.cmd"
}
}
Note that the secModel, secName, secPassword, and secLevel tags must still
be present, even though they are not used. Finally, we need to add an
entry inside the "info" block. This entry will refer to the "params" by
name. An entry inside the "info" block represents an action that will be
taken when an event occurs. If there are five entries inside "info", and
each one refers to the same script that script will be executed five times
for each event (for example, to send traps to five different destinations).
info = {
MgrTrap = {
host = myMgrHost
port = 162
tags = event
params = SnmpTrap
}
Email = {
host = none
port = 0
tags = event
params = SendEmail
}
}
Again, the "host" and "port" tags must be present, even though the script
might not use them.
Now restart the agent service, and the send_email.cmd script will be executed
with each new event.
Example Scripts
---------------
For a complete example of event processing, you can look at the script
that the agent uses to send an SNMP trap:
/install/bin/HALEventTarget-trap.cmd
Module Data
-----------
Data gathered by all the modules within an agent is available via SNMP.
To obtain MIBs for PrimeAlert products, and for additional information
on integrating module data into a third party management framework,
please contact Halcyon Monitoring Solutions.
Alarm Thresholds and Actions
----------------------------
Changing the default alarm thresholds and actions on a standalone agent
requires editing some agent configuration files. For assistance changing
alarm thresholds or actions, please contact Halcyon Support (see the
section "Contact Information" at the end of this file).
Logging
-------
The Neuron Agent for Microsoft Windows creates several log files that can
be used for debugging purposes. These log files use a special format
called clog. Clog files are circular log files that remain at a fixed
size. The following tools can be used to view the log files:
\install\bin\ctail.exe: This is similar to the UNIX command
tail. It displays the last few lines of a file. New lines are displayed
as they are added to the file.
\install\bin\ccat.exe: This is similar to the UNIX command
cat. It prints the whole file on standard output.
The following log files are created by the agent --
\local\log\agent.log:
This log file contains runtime information about the Neuron Agent
for Microsoft Windows. Lines containing critical error messages begin
with "error".
\local\log\agentStatus.log:
This log file contains events generated by the Neuron Agent for
Microsoft Windows.
SNMP Get Community
------------------
For most modules, the SNMP community 'public' can be used to poll the
agent for data. However, some modules are not accessible using 'public'.
The Neuron agent was designed for use with SNMP v2usec, which
supports contexts. Some modules are loaded with user-specified contexts.
This allows multiple instances of these modules to use the same SNMP
OIDs. Each module instance is accessed individually by specifying the
instance's context.
Since SNMP v1 and v2c do not support contexts, these modules
be accessed using the following SNMP community:
public:
where is the module's instance, as specified when
the module was loaded. To determine a module's instance, view
the file:
\local\cfg\base-modules-d.dat
Each line of this file represents a loaded module, and starts
with:
+ = ...
For example, if the base-modules-d.dat file contains a line
that starts with 'HALProcessAlert+Process_Monitor', then to
access this module's MIB, use the SNMP community
'public:Process_Monitor'.
License
=======
Please read the license agreement in the following file:
- License.txt
Without purchasing a license, the modules that are part of the
Neuron Agent for Microsoft Windows will only operate for an
evaluation period of 30 days from installation.
If you wish to purchase a license to use the Neuron Agent for
Microsoft Windows, please contact us (see "Contact Information").
Contact Information
===================
Halcyon Monitoring Solutions, Inc.
http://www.HalcyonInc.com
mailto:info@HalcyonInc.com
Tel: 416-932-4647
Fax: 416-932-4711
---//---