======================================================================
Halcyon Neuron Agent for Solaris
Version 3.4.0
README.install
======================================================================
Overview
======================================================================
This README.install file describes how to install and setup the
Halcyon Neuron agent.
It consists of the following sections:
- Installation Instructions
. Definitions
. Non-root User Considerations
. Extracting the Distribution
. Installing the Agent
. Adding Whole Root Zone Support
. Adding Sparse Root Zone Support
. Installation Log File
- Uninstallation Instructions
. Uninstallation Log File
Installation Instructions
======================================================================
Definitions
======================================================================
PAROOT This environment variable contains the directory
where the agent binaries, libraries and default
configuration files are installed. The user
configures this directory during installation of
the agent. The default location is
"/opt/Neuron".
To determine the value of PAROOT after installation,
run the command:
$ pkgparam HALniasag BASEDIR
PADIR This environment variable contains the directory
where the agent stores configuration and log files.
The user configures this directory during
installation of the agent. The default location is
"/var/opt/Neuron".
To determine the value of PADIR, after installation,
run the command:
$ pkgparam HALniasag LOCALDIR
Agent Host A host where a Neuron Agent is installed and
running. This host must be a Solaris host, and it
contains the package HALniasag.
Non-root User Considerations
======================================================================
Although the Neuron Agent can be configured to run as a non-root
user, installation must be undertaken by the root (uid 0) user.
When running as a non-root user some Neuron modules will require
additional external configuration of privileges or permissions
to function properly.
PrimeAlert LogFileMonitor requires that the Neuron Agent user
have read permission for the files being monitored.
PrimeAlert DirectoryMonitor requires that the Neuron Agent user
have read and search permission for the directory and all of the
contents of the directories being monitored.
The Zone CPU Cap metrics in the Zone Statistics section of
PrimeAlert SystemMonitor requires one of the following:
A) The Neuron Agent be configured to run as root.
B) The Neuron Agent user must be given privileges equivalent
to those of root as is necessary to use 'privileged
resource controls'.
C) The lowerable flag must be set for the zone.cpu-cap
resource control.
Without one of the above, the Zone CPU Cap metrics will
appear as "-1" in the Zone Utilization table.
Extracting the Distribution File
======================================================================
The Neuron Agent for Solaris distribution file,
HALNeuronSolaris_[version].tar.(Z|gz), must be extracted on a UNIX host before
any packages can be installed. For example, assume that the distribution
file has been copied to the /tmp/install directory, and will be extracted
there. In this case, the procedure for extracting the distribution file is:
$ su -
# mkdir -p /tmp/install
# cd /tmp/install
# uncompress HALNeuronSolaris_[version].tar.Z
or gzip -d HALNeuronSolaris_[version].tar.gz
# tar xvf HALNeuronSolaris_[version].tar
In this case, the directory /tmp/install/HALNeuronSolaris_[version] represents
the installation source directory, [SOURCE_DIR], which is referenced
below.
Installing the Agent
======================================================================
The procedure described in this sub-section should be performed on any
Solaris host that is being upgraded to the latest version of the
Neuron Agent for Solaris, or that is receiving the Neuron Agent for
Solaris for the first time.
Login to a Solaris host as root. Extract the Neuron Agent for Solaris
distribution file (see the above section 'Extracting the Distribution
File') in a temporary location, and then run the script
HALNeuronSolaris-install.sh, e.g.:
$ su -
# cd [SOURCE_DIR]
# ./HALNeuronSolaris-install.sh -n
During installation, you are requested to enter the following
information:
- User name and group name. The Neuron agent runs under the
user selected at install time. The selected user can be either
root or non-root. In addition, files under both the Neuron
install directory and configuration directory will be owned by
the selected user and group.
Please note: in order for some Neuron modules to function
properly, additional privileges should be granted to the
selected user. Please see the 'Non-root User Considerations'
section above.
- Base directory. This is the directory where binaries and
default configuration files are installed (see PAROOT above).
The default value is "/opt/Neuron".
- Directory for configuration and log files. (See PADIR above).
The default value is "/var/opt/Neuron".
- Agent Port: The SNMP port used by the agent. The default
value is 6681.
- SNMP manager host/port: If you elect to send SNMP traps to
a manager, you will be prompted for the hostname and port of
a machine which will receive an SNMP trap for each agent event.
See the README file for an explanation of events.
- Module setup: If you elect to setup modules, the module loader
utility will start and you will be given a menu with options to
load, unload or edit modules. See the README file for further
details.
After the previous information has been provided, the install script
modifies the following configuration files:
$PADIR/cfg/domain-config.x
$PADIR/cfg/HALEventTarget-config.x
These files are the main configuration files for your Neuron Agent.
Finally, the install script displays some information on additional
shell scripts that can be used to start, stop, or inquire about the
status of the Neuron Agent for Solaris.
At this stage, the installation of the Neuron Agent component is
complete. No host reboot is required. If you have upgraded the agent
or any of its bundled modules, the agent must be restarted. For an
initial install, the agent must simply be started. The "na" script
controls the agent. Use the following commands to control the agent:
- 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: Prints the status of the Neuron Agent
(is the agent running or not).
The shell script can be found in $PAROOT/bin.
Adding Whole Root Zone Support
======================================================================
To monitor a whole root zone in Solaris, simply install the Neuron agent
within the zone as normal.
Adding Sparse Root Zone Support
======================================================================
If your version of Solaris supports sparse root zones, then the Neuron
agent can be configured to run in each sparse zone. The general steps
to take are:
1. Install the Neuron Agent normally in the global zone. Ensure
that you choose a PADIR (configuration and logs, typically
/var/opt/Neuron) that is NOT shared with any sparse zones.
2. The PAROOT directory (base install dir, typically /opt/Neuron)
must be shared/visible in the sparse zone.
3. Run /opt/Neuron/sbin/HALZoneConfig.sh as root within the sparse
zone. This configures and enables the agent.
For example, for a sparse zone which does not share the /opt directory
with with the Global Zone, the following steps would need to be taken:
1. Install the Neuron Agent normally in the global zone.
2. Create the PAROOT directory in the local zone.
# zlogin [name of local zone] mkdir /opt/Neuron
3. Create a loopback mount from the installation directory in the global
zone to the local zone.
# mount -F lofs $PAROOT [path to local zone]/root/opt/Neuron
4. Make the mount permanent in the local zone.
# zonecfg -z [name of local zone]
> add fs
> set dir=/opt/Neuron
> set special=$PAROOT
> set type=lofs
> end
> commit
> exit
5. Configure and start the Neuron agent in the local zone.
# zlogin [name of local zone]
# /opt/Neuron/sbin/HALZoneConfig.sh
# /opt/Neuron/bin/na start agent
Detailed example:
The following steps will configure the Neuron agent in the
zone 'ember', if '/export/ember' is the path to this zone:
# zlogin ember mkdir /opt/Neuron
# mount -F lofs /opt/Neuron /export/ember/root/opt/Neuron
# zonecfg -z ember
> add fs
> set dir=/opt/Neuron
> set special=/opt/Neuron
> set type=lofs
> end
> commit
> exit
# zlogin ember
# /opt/Neuron/sbin/HALZoneConfig.sh
# /opt/Neuron/bin/na start agent
Installation Log File
======================================================================
To view the installation log on a Solaris host, see the file:
$PADIR/install/HALNeuronSolaris-install_[YYYYMMDD]-[HHMMSS].log
Uninstallation Instructions
======================================================================
NOTE: Before removing the Neuron Agent for Solaris, first remove all
modules that are installed on the host.
Issue the following commands to uninstall the agent:
# cd $PADIR/uninstall
# ./HALUninstall.sh
NOTE: 1) If your version of Solaris supports zones, then the commands to
uninstall Neuron must be executed in the global zone. Any Neuron
agents configured in the local zones will automatically be
stopped and removed.
2) You may have to manually remove the permanent loopback mount point
for each sparse zone by issuing a command similar to the following
in the global zone:
# umount [path to local zone]/root/opt/Neuron
# zonecfg -z [name of local zone]
> remove fs dir=/opt/Neuron
> commit
Uninstallation Log File
======================================================================
To view the uninstallation log on a Solaris host, see the file:
$PADIR/uninstall/log/uninstall.log.[YYYYMMDD]-[HHMMSS]
---//---