Halcyon Neuron Agent for Tru64
Version 2.0.0
README
-----------------------------------------------------------------------
Readme Contents
===============
* Readme Contents
* Included Components
* Informational Text Files
* Installation and Uninstallation Instructions
* Troubleshooting
* Overview
* Using the Neuron Agent for Tru64
* Integrating the Neuron Agent with Third Party Frameworks
* Configuring Modules
* Bundled Modules
* License
* Contact Information
Included Components
===================
This distribution includes the following products:
PrimeAlert Agent for Tru64
PrimeAlert SystemMonitor for Tru64
PrimeAlert HardwareMonitor
PrimeAlert MIB-II System
PrimeAlert AgentHealth
PrimeAlert DirectoryMonitor
PrimeAlert FileSizeMonitor
PrimeAlert LogFileMonitor
PrimeAlert ProcessMonitor
PrimeAlert Reporter (Agent component)
PrimeAlert WebAgent
Informational Text Files
========================
A number of useful informational text files are included with this
distribution:
- README
- README.install
- TroubleShooting
- ReleaseNotes
- LICENSE
- COPYRIGHT
These files are located in the base directory of the distribution
tarball, and after installation, in the directory:
$PADIR/install/HALNeuron
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').
Overview
========
The PrimeAlert Agent for Tru64 monitors the health and performance
of a Tru64 machine.
This distribution contains the Neuron agent, which is a PrimeAlert Agent
configured to operate without a PrimeAlert Portal server, and is
designed to integrate with third party management frameworks.
The following modules are provided with this release:
- PrimeAlert SystemMonitor for Tru64*
- PrimeAlert HardwareMonitor *
- PrimeAlert MIB-II System*
- PrimeAlert AgentHealth*
- PrimeAlert DirectoryMonitor
- PrimeAlert FileSizeMonitor
- PrimeAlert LogFileMonitor
- PrimeAlert ProcessMonitor
- PrimeAlert Reporter*
- PrimeAlert WebAgent*
(*) These modules are loaded by default when the Neuron Agent
for Tru64 is first started.
Using the Neuron Agent for Tru64
======================================
Starting the Agent
------------------
The Neuron Agent for Tru64 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, add log files patterns, 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 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 Tru64 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/alpha/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/alpha/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 Tru64. Lines containing critical error messages begin with "error".
$PADIR/log/agentStatus.log,
This log file contains events generated by the Neuron Agent for
Tru64.
$PADIR/log/agentEventQueue.log:
This log file is used internally for event dispatching.
Configuring Modules
===================
Modules may be loaded, modified or unloaded using the web interface.
The Neuron agent also comes with a command line utility ("module_loader")
which performs the same functions:
Starting the Module Loader
--------------------------
To start the module loader process on Tru64, first become root:
$ su -
Next, setup the required environment variables (PADIR, PAROOT, PATH
and INTERFACE_PATH):
# PAROOT=/opt/Neuron
# eval `$PAROOT/bin/na`
Finally, invoke the utility:
# module_loader
Loading a module
----------------
After starting the module loader, a menu is displayed with three
options:
Halcyon PrimeAlert Agent
Module Configuration Utility
Main Menu
---------
1) Load a module
2) Unload a module
3) Edit a module
Q) Quit
Select an action [Q]: 1
Note that the character in brackets at the prompt is the default
selection. Hitting enter will pick this selection.
Select "1" at the prompt and hit enter to bring up the module loading
menu, which contains a list of all the installed modules that you
can load:
Load a module:
--------------
1) PrimeAlert ScriptRunner
2) PrimeAlert MIB-II System
PrimeAlert Agent Statistics (already loaded)
3) PrimeAlert SystemAlert
B) Back to main menu
Q) Quit
Select a module to load [B]: 1
Select the module you would like to load from the list. This will
bring up the module parameters menu, where you can see the name and
description of the module, as well as set any load-time parameters.
We'll show the PrimeAlert ScriptRunner module as an example:
Set module parameters:
----------------------
Module = HALScriptRunner
Module Name = PrimeAlert ScriptRunner
Module Description =
The PrimeAlert ScriptRunner module allows the agent
to run monitoring and control scripts and drive alarms
based on their status.
Version = 1.0.5
Enterprise = halcyon
Module Type = Local Application
1) * Instance =
2) * Description =
3) * Script Name =
4) Script Parameters =
5) * Script Schedule =
B) Back to main menu
S) Save changes (Will restart agent process)
Q) Quit
(*) indicates a required field
Select a parameter to set [S]:
The parameters that you can set are shown with a number at the left
side. Items marked with a "*" are parameters that must be set before
the module can be loaded. For each of these parameters, select its
number and then enter a value at the prompt:
Select a parameter to set [S]: 1
Instance []: myInstance
The value you choose will then be displayed next to the parameter
name in the module parameters menu. When you are finished specifying
parameters, you can choose to abandon your changes by selecting "B"
or "Q", or you can save the changes by selecting "S". This will
restart the agent with the new module loaded, and you will be
returned to the main menu.
Unloading a module
------------------
To unload a module, select "2" at the main menu. This will bring
up an unload module menu with a list of all the currently loaded
modules:
Unload a module:
----------------
1) PrimeAlert AgentHealth
2) PrimeAlert Hardware Monitor
3) PrimeAlert SystemMonitor
B) Back to main menu
Q) Quit
Note: Unloading a module will restart the agent process
Select a module to unload [B]: 2
Select which module you would like to unload. The agent will be
restarted without that module, and you will be returned to the
main menu.
Editing module parameters
-------------------------
To change the parameters of a loaded module, select "3" from the
main menu. This will bring up the set parameters menu that you
used when originally loading the module. However, there may be
some parameters that you cannot edit. To change one of these
values, you must unload the module and then load it again from
scratch. When you are done changing parameter values, select
"S" to save your changes. This will restart the agent with the
modified module parameters, and you will be returned to the
main menu.
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 Tru64
------------------------------------
The PrimeAlert SystemMonitor for Tru64 provides information about
the operating system and its components. The following sub-folders
are available:
1. User Statistics: Displays information about the current console
user, the number of current users and sessions, and the primary
user of the system.
2. Process Statistics: Displays information about current processes
on your Tru64 system grouped by their state. It also shows the
total number of processes and the process capacity as well as
the process limit. Probe commands provide a detailed view of
processes in different states and ordered by several criteria.
3. System Load: Provides information about the current system load
(1 min, 5 min and 15 min load averages).
4. CPU Usage: Provides information about the current usage of the
CPU. Shown are idle time, busy time, system time, user time, and
the average CPU usage.
5. Swap Usage: Displays information about the total and available swap
space and the current usage of swap memory. A probe command provides
detailed information about allocated swap space.
6. Filesystem Usage: Displays information about mounted filesystems.
For each filesystem the total size, available space, used space,
and the change rate of used space are shown.
7. Network Interfaces: Lists installed network interfaces and reports
input/output packet errors and collisions. Probe commands can be
used to obtain information about route tables and protocols.
8. TCP Connections: Provides information about existing TCP
connections. Probe commands generate a detailed view of network
statistics for several protocols (e.g. Inet, TCP, UDP).
9. IPC Facilities: Displays information about IPC message queues,
shared memory, and semaphores. Probe commands can be used to
obtain detailed information about these IPC facilities.
PrimeAlert MIB-II System
------------------------
The PrimeAlert MIB-II System module provides information about the MIB
used by the Neuron Agent for Tru64.
PrimeAlert DirectoryMonitor
---------------------------
PrimeAlert DirectoryMonitor can be used to monitor the size of
directories on a host. The subdirectories and links may be viewed
recursively using a window accessible from the module's pop-up menu.
PrimeAlert FileSizeMonitor
--------------------------
PrimeAlert FileSizeMonitor can be used to monitor the status of
files on a host. The size of the file, its rate of growth, and its
last modification time are displayed in the console.
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 for a PrimeAlert Agent.
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 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
Neuron Agent for Tru64 will operate for a trial period of 30 days.
If you wish to purchase a license to use the Neuron Agent for
Tru64, 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
---//---
</pre>