Commands Reference, Volume 2

haemctrl Command

Purpose

Starts the Event Management subsystem.

Syntax

haemctrl {-a | -s | -k | -d | -c | -u | -t | -o | -r | -h}

Description

Event Management is a distributed subsystem of RSCT that provides a set of high availability services for the IBM RS/6000 SP. By matching information about the state of system resources with information about resource conditions that are of interest to client programs, it creates events. Client programs can use events to detect and recover from system problems, thus enhancing the availability of the SP system.

The haemctrl control script controls the operation of the Event Management subsystem. The subsystem is under the control of the System Resource Controller (SRC) and belongs to a subsystem group called haem. Associated with each subsystem is a daemon.

The haemctrl script also controls the operation of the AIX Resource Monitor subsystem. The subsystem is under SRC control and also belongs to the haem subsystem group. Associated with each subsystem is a daemon.

Instances of the Event Management and AIX Resource Monitor subsystems execute on the control workstation and on every node of a system partition. Because Event Management provides its services within the scope of a system partition, these subsystems are said to be system partition-sensitive. This control script operates in a manner similar to the control scripts of other system partition-sensitive subsystems. It can be issued from either the control workstation or any of the system partition's nodes.

From an operational point of view, the Event Management subsystem group is organized as follows:

Subsystem

Event Management

Subsystem Group

haem

SRC Subsystem

haem

The haem subsystem is associated with the haemd daemon.

The subsystem name on the nodes is haem. There is one of each subsystem per node and it is associated with the system partition to which the node belongs.

On the control workstation, there are multiple instances of each subsystem, one for each system partition. Accordingly, the subsystem names on the control workstation have the system partition name appended to them. For example, for system partitions named sp_prod and sp_test, the subsystems on the control workstation are named haem.sp_prod and haem.sp_test.

haemaixos

The haemaixos subsystem is associated with the harmad daemon.

The subsystem name on the nodes is haemaixos. There is one of each subsystem per node and it is associated with the system partition to which the node belongs.

Daemons

haemd and harmad

The haemd daemon provides the Event Management services. The harmad daemon is the resource monitor for AIX operating system resources.

The haemctrl script is not normally executed from the command line. It is normally called by the syspar_ctrl command during installation of the system, and partitioning or repartitioning of the system.

The haemctrl script provides a variety of controls for operating the Event Management subsystem:

Adding, starting, stopping, and deleting the subsystem
Cleaning up the subsystems, that is, deleting them from all system partitions
Unconfiguring the subsystems from all system partitions
Turning tracing on and off
Refreshing the Event Management subsystem

Before performing any of these functions, the script obtains the current system partition name and IP address (using the spget_syspar command) and the node number (using the node_number) command. If the node number is zero, the control script is running on the control workstation.

Except for the clean and unconfigure functions, all functions are performed within the scope of the current system partition.

Adding the Subsystem

When the -a flag is specified, the control script uses the mkssys command to add the Event Management and AIX Resource Monitor subsystems to the SRC. The control script operates as follows:

It makes sure that the haem and haemaixos subsystems are stopped.
It gets the port number for the haem subsystem for this system partition from the Syspar_ports class of the System Data Repository (SDR) and ensures that the port number is set in the /etc/services file. If there is no port number in the SDR and this script is running on the control workstation, the script obtains a port number. If the script is running on a node and there is no port number in the SDR, the script ends with an error. The range of valid port numbers is 10000 to 10100, inclusive.
The service name that is entered in the /etc/services file is haem.syspar_name.
It removes the haem and haemaixos subsystems from the SRC (just in case they are still there).
It adds the haem subsystem to the SRC. On the control workstation, the IP address of the system partition is specified to be supplied as an argument to the daemon by the mkssys command.
It adds the haemaixos subsystem to the SRC.
It adds an entry for the haem group to the /etc/inittab file. The entry ensures that the group is started during boot. However, if haemctrl is running on a High Availability Control Workstation (HACWS), no entry is made in the /etc/inittab file. Instead, HACWS manages starting and stopping the group.
The haemrm group is added using the mkgroup command, if it does not already exist. Setting the environment variable HAEM_NO_GROUP=1 prevents the group from being created. To prevent the haem subsystem from logging an error message indicating that the haemrm group is missing, the HAEM_NO_GROUP environment variable must be placed in the /etc/environment file. Any errors that occur are written to a log file named /var/ha/log/em.mkgroup.
The /var/ha/lck/haem and /var/ha/soc/haem directories are created, if they don't already exist. Any errors that occur are written to a log file named /var/ha/log/em.mkdir.
On the control workstation, it creates the Event Management Configuration Database (EMCDB). First, it runs the haemloadcfg command to load the SDR with the Event Management configuration data that is contained in the haemloadlist file. Then, it runs the haemcfg command to compile the data in the SDR and create the binary Event Management Configuration Database. Any errors that occur are written to a log file named /var/ha/log/em.loadcfg.syspar_name.
Then it gets the port number for the subsystem from the SP_ports class of the System Data Repository (SDR) and ensures that the port number is set in the /etc/services file. This port number is used for remote connections to Event Management daemons that are running on the control workstation. If there is no port number in the SDR, the script obtains one and sets it in the /etc/services file. The range of valid port numbers is 10000 to 10100, inclusive.

The service name is haemd.

Starting the Subsystem

When the -s flag is specified, the control script uses the startsrc command to start the Event Management subsystem, haem, and the AIX Resource Monitor subsystem, haemaixos.

Stopping the Subsystem

When the -k flag is specified, the control script uses the stopsrc command to stop the Event Management subsystem, haem, and the AIX Resource Monitor subsystem, haemaixos.

Deleting the Subsystem

When the -d flag is specified, the control script uses the rmssys command to remove the Event Management and AIX Resource Monitor subsystems from the SRC. The control script operates as follows:

It makes sure that the haem and haemaixos subsystems are stopped.
It removes the haem and haemaixos subsystems from the SRC using the rmssys command.
It removes the port number from the /etc/services file.
If there are no other subsystems remaining in the haem group, it removes the entry for the haem group from the /etc/inittab file.

Cleaning Up the Subsystems

When the -c flag is specified, the control script stops and removes the Event Management subsystems for all system partitions from the SRC. The control script operates as follows:

It stops all instances of subsystems in the subsystem group in all partitions, using the stopsrc -g haem command.
It removes the entry for the haem group from the /etc/inittab file.
It removes all instances of subsystems in the subsystem group in all partitions from the SRC using the rmssys command.
It removes all Event Management entries from the /etc/services file. These include the port numbers for the subsystems as well as the port number used for remote connections.

Unconfiguring the Subsystems

When the -u flag is specified, the control script performs the function of the -c flag in all system partitions and then removes all port numbers from the SDR allocated by the Event Management subsystems.

Note

The -u flag is effective only on the control workstation.

Prior to executing the haemctrl command with the -u flag on the control workstation, the haemctrl command with the -c flag must be executed from all of the nodes. If this subsystem is not successfully cleaned from all of the nodes, different port numbers may be used by this subsystem, leading to undefined behavior.

Turning Tracing On

When the -t flag is specified, the control script turns tracing on for the haemd daemon, using the haemtrcon command. Tracing for the harmad daemon is also enabled, using the traceson command.

Turning Tracing Off

When the -o flag is specified, the control script turns tracing off for the haemd daemon, using the haemtrcoff command. Tracing for the harmad daemon is also disabled, using the tracesoff command.

Refreshing the Subsystem

When the -r flag is specified, the control script refreshes the subsystem using the refresh command. This results in the Event Management subsystem attempting to use the current SP Trusted Services authentication methods. Note that this command only initiates the refresh operation. Use the lssrc -ls haem.syspar_name command on the control workstation or the lssrc -ls haem command on a node to determine the current security state of the Event Management subsystem within the system partition.

Logging

While it is running, the Event Management daemon normally provides information about its operation and errors by writing entries to the AIX error log. If it cannot, errors are written to a log file called /var/ha/log/em.default.syspar_name.

Flags

-a: Adds the subsystem.
-s: Starts the subsystem.
-k: Stops the subsystem.
-d: Deletes the subsystem.
-c: Cleans the subsystems, that is, deletes them from all system partitions.
-u: Unconfigures the subsystems from all system partitions.
-t: Turns tracing on for the subsystem.
-o: Turns tracing off for the subsystem.
-r: Refreshes the subsystem.
-h: Displays usage information.

Parameters

None.

Security

You must have root privilege and write access to the SDR to run this command.

Exit Status

0: Indicates the successful completion of the command.
1: Indicates that an error occurred.

Restrictions

This command is valid in a PSSP environment only.

Standard Output

When the command executes successfully, it writes the following informational messages:

Reading Event Management data for partition syspar_name
 
CDB=new_EMCDB_file_name Version=EMCDB_version_string

Standard Error

This command writes error messages (as necessary) to standard error.

Examples

To add the Event Management subsystem to the SRC in the current system partition, set the SP_NAME environment variable to the appropriate system partition name and enter:
```
haemctrl -a
```
To start the Event Management subsystem in the current system partition, set the SP_NAME environment variable to the appropriate system partition name and enter:
```
haemctrl -s
```
To stop the Event Management subsystem in the current system partition, set the SP_NAME environment variable to the appropriate system partition name and enter:
```
haemctrl -k
```
To delete the Event Management subsystem from the SRC in the current system partition, set the SP_NAME environment variable to the appropriate system partition name and enter:
```
haemctrl -d
```
To clean up the Event Management subsystem on all system partitions, enter:
```
haemctrl -c
```
To unconfigure the Event Management subsystem from all system partitions, on the control workstation, enter:
```
haemctrl -u
```
To turn tracing on for the Event Management daemon in the current system partition, set the SP_NAME environment variable to the appropriate system partition name and enter:
```
haemctrl -t
```
To turn tracing off for the Event Management daemon in the current system partition, set the SP_NAME environment variable to the appropriate system partition name and enter:
```
haemctrl -o
```

Location

/usr/sbin/rsct/bin/haemctrl

Files

/var/ha/log/em.default.cluster_name: Contains the default log of the haemd daemon on the cluster named cluster_name.
/var/ha/log/em.cp: Contains a log of any errors that occurred while copying the Event Management Configuration Database.
/var/ha/log/em.trace.cluster_name: Contains the trace log of the haemd daemon on the cluster named cluster_name.
/var/ha/log/em.mkgroup: Contains a log of any errors that occurred while creating the haemrm group.
/var/ha/log/em.mkdir: Contains a log of any errors that occurred while creating the /var/ha/lck/haem and /var/ha/soc/haem directories.

Related Information

Commands: haemcfg, haemd, haemloadcfg, haemtrcoff, haemtrcon, lssrc, startsrc, stopsrc, syspar_ctrl

RSCT Event Management Programming Guide and Reference

AIX Commands Reference

Information about the System Resource Controller (SRC) in AIX General Programming Concepts: Writing and Debugging Programs