<PRE>
Halcyon PrimeAlert (R) Neuron Agent for IBM AIX
Version 3.0.0
README
-----------------------------------------------------------------------
Readme Contents
===============
* Readme Contents
* Included Components
* Acknowledgements
* Informational Text Files
* Installation and Uninstallation Instructions
* Troubleshooting
* Overview
* Using the Neuron Agent for IBM AIX
* Integrating the Neuron Agent with Third Party Frameworks
* Bundled Modules
* License
* Contact Information
Included Components
===================
This distribution includes the following PrimeAlert products:
PrimeAlert Neuron Agent for IBM AIX
PrimeAlert SystemMonitor for IBM AIX
PrimeAlert MIB-II System
PrimeAlert AgentHealth
PrimeAlert HardwareMonitor for IBM AIX
PrimeAlert Reporter
PrimeAlert WebAgent
PrimeAlert NeuronPortal
PrimeAlert ScriptRunner
The PrimeAlert modules bundled with the PrimeAlert Neuron Agent
for IBM AIX provide the agent with a basic level of functionality.
Acknowledgements
================
This distribution includes software developed by the OpenSSL Project
for use in the OpenSSL Toolkit. (http://www.openssl.org/)
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:
$PAROOT/powerpc/sbin/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). A copy
of the GNU General Public License Version 2 is included with this
distribution.
Informational Text Files
========================
A number of useful informational text files are included with this
distribution:
- README
- README.install
- TroubleShooting
- ReleaseNotes
- LICENSE
- COPYRIGHT
- GPL.txt
These files are located in the base directory of the distribution
tarball, and after installation, in the directory:
$PADIR/install/HALNeuronAIX
Note: PAROOT and PADIR are set to /opt/Neuron and /var/opt/Neuron
respectively after installation.
Installation and Uninstallation Instructions
============================================
For installation or uninstallation instructions, refer to the file
README.install (see the above section 'Informational Text Files').
Troubleshooting
===============
For troubleshooting information, refer to the TroubleShooting file
(see the above section 'Informational Text Files').
The release notes file, ReleaseNotes, which is located in the same
places as the TroubleShooting file, is also a valuable reference.
It contains information about bug fixes, enhancements, known problems,
and upgrade strategy for the current release.
Overview
========
The PrimeAlert Neuron Agent for IBM AIX monitors the health and statistics
of a host running IBM AIX. It works as a stand-alone agent, and is designed
to integrate with third party management frameworks.
The following modules are provided with this release:
- PrimeAlert SystemMonitor for IBM AIX
- PrimeAlert MIB-II System
- PrimeAlert AgentHealth
- PrimeAlert HardwareMonitor for IBM AIX
- PrimeAlert Reporter
- PrimeAlert WebAgent
These modules are loaded by default when the PrimeAlert Neuron Agent
for IBM AIX is first started; note that PrimeAlert MIB-II System cannot
be unloaded by the user.
Using the Neuron Agent for IBM AIX
====================================
Starting the Agent
------------------
The PrimeAlert Neuron Agent for IBM AIX is controlled by the na script
that is located in $PAROOT/bin after installation. The controlling
commands are:
- na start agent: starts the Neuron Agent
- na stop agent: stops the Neuron Agent
- na restart agent: restarts the Neuron Agent (stop and start)
- na status agent: returns status information about the
Neuron Agent (agent up/down)
Configuring the Agent
---------------------
Once started, you may login to the Agent using a web browser,
by pointing the browser at the agent host (using the WebAgent
HTTP port specified during installation). You will be prompted
for a username and password. The default username is "admin", and
the default password is "admin".
Note: the HTTP port, username and password may all be changed after
installation by editing the WebAgent module.
Once logged in, you may use the web interface to load, edit and
unload modules, and set alarm thresholds and actions.
Data objects may be "tracked" (added to Reporter). Historical data
for tracked objects may be graphed or exported to a spreadsheet by
nagivating to the Reporter module, and selecting the desired actions
from the table cell popup menus.
Integrating the Neuron Agent with Third Party Frameworks
=========================================================
The Neuron Agent includes several features that facilitate
integration with a third-party management framework, without the
need for a PrimeAlert Portal 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 PrimeAlert 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:
$PAROOT/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:
$PADIR/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 must be restarted:
$PAROOT/bin/na restart agent
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 shell
commands:
# extract event parameters from command line (format is -[name] [value])
while [ $# -gt 0 ]; do
case $1 in
-targetHost) shift; targetHost=$1;;
-targetPort) shift; targetPort=$1;;
-ttyp) shift; ttyp=$1;;
-module) shift; module=$1;;
-context) shift; context=$1;;
-description) shift; description=$1;;
-open_time) shift; open_time=$1;;
-close_time) shift; close_time=$1;;
-severity) shift; severity=$1;;
-url) shift; url=$1;;
-path) shift; path=$1;;
-hostname) shift; hostname=$1;;
-ip) shift; ip=$1;;
-port) shift; port=$1;;
esac
shift;
done
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 $PADIR/bin. The script
should be executable, and as a security precaution, the file must be owned
by root.
Now that the script is finished, the agent configuration must be modified to
use it. Edit the file $PADIR/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.sh:
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.sh"
}
}
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, and the send_email.sh script
will be executed with each new event:
# $PAROOT/bin/na restart agent
Example Scripts
---------------
For a complete example of event processing, you can look at the script
that the agent uses to send an SNMP trap:
$PAROOT/bin/HALEventTarget-trap
Module Data
-----------
Data gathered by all the modules within an agent may be viewed using
the web interface.
Data is also 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 (see the section "Contact Information" at
the end of this file).
Logging
-------
The Neuron Agent for IBM AIX 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:
$PAROOT/bin/ctail: This is similar to the Unix command "tail". It
displays the last few lines of a file. New lines can be displayed
as they are added to the file. Run the command with no arguments
to get instructions on its usage.
$PAROOT/bin/ccat: This is similar to the Unix command "cat".
It prints the whole file on standard output.
The agent creates the following log files --
$PADIR/log/agent.log:
This log file contains runtime information about the Neuron Agent
for IBM AIX. Lines containing critical error messages begin with "error".
$PADIR/log/agentStatus.log,
This log file contains events generated by the Neuron Agent for IBM AIX.
$PADIR/log/agentEventQueue.log:
This log file is used internally for event dispatching.
Bundled Modules
===============
PrimeAlert AgentHealth
----------------------
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 SystemMonitor for IBM AIX
----------------------------------
The PrimeAlert SystemMonitor for IBM AIX provides information about the
operating system and its components.
PrimeAlert MIB-II System
------------------------
The PrimeAlert MIB-II System module provides information about the MIB
used by the PrimeAlert Agent for IBM AIX. This module cannot be unloaded
by the user.
PrimeAlert HardwareMonitor for IBM AIX
----------------------------------
The PrimeAlert HardwareMonitor for IBM AIX provides information about the
hardware and its components.
PrimeAlert Reporter
-------------------
PrimeAlert Reporter logs historical values for monitored entities in a
database. Data can be listed, exported, or graphed using PrimeAlert
WebPortal or PrimeAlert WebAgent.
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.
License
=======
Please read the license agreement in the file LICENSE located in this
directory.
Without purchasing a license, the modules that are part of the
PrimeAlert Neuron Agent for IBM AIX will only operate for a trial
period of 30 days.
If you wish to purchase a license to use the PrimeAlert Neuron Agent
for IBM AIX, please contact Halcyon Sales (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
---//---