Example of the view shown in /proc/ham

Updated: May 06, 2022

Consider the following simple example where a HAM is monitoring inetd and restarts it when it dies:

# ls -al /proc/ham
total 2
-r--------  1 root      root            175 Aug 30 23:05 .info
dr-x------  1 root      root              1 Aug 30 23:06 inetd

The .info file at the highest level provides information about the HAM and the Guardian, as well as an overview of the entities and other objects in the system:

# cat /proc/ham/.info
Ham Pid            : 10993674
Guardian Pid       : 10997782
Ham Failures       : 0
Guardian Failures  : 0
Num Entities       : 1
Num Conditions     : 1
Num Actions        : 1

In this case the only entity being monitored is inetd, which appears as a directory at the top level under /proc/ham:

# ls -al /proc/ham/inetd
total 2
-r--------  1 root      root            173 Aug 30 23:06 .info
dr-x------  1 root      root              1 Aug 30 23:06 death

# cat /proc/ham/inetd/.info
Path            : inetd
Entity Pid      : 11014167
Num conditions  : 1
Entity type     : ATTACHED
Stats:
Created         : 2001/08/30 23:04:49:930148650
Num Restarts    : 0

As you can see, the .info provides information and statistics relating to the inetd entity that is being monitored. The information is generated dynamically and contains up-to-date data for each entity.

The inetd entity has associated with it only one condition (i.e., death), which is triggered when the entity dies.

# ls -al /proc/ham/inetd/death
total 2
-r--------  1 root      root            126 Aug 30 23:07 .info
-r--------  1 root      root            108 Aug 30 23:07 restart

# cat /proc/ham/inetd/death/.info
Path            : inetd/death
Entity Pid      : 11014167
Num Actions     : 1
Condition ReArm : ON
Condition type  : CONDDEATH

Similarly, there's only one action associated with this death condition: the restart mechanism. Each action under the condition appears as a file under the appropriate condition directory. The file contains details about the action that will be performed when the condition is triggered.

# cat /proc/ham/inetd/death/restart
Path         : inetd/death/restart
Entity Pid   : 11014167
Action ReArm : ON
Restart Line : /usr/sbin/inetd -D
Note: If inetd isn't a self-attached entity, you need to specify the -D option to it, to force inetd to daemonize by calling procmgr_daemon() instead of by calling daemon(). The HAM can see death messages only from self-attached entities, processes that terminate abnormally, and tasks that are running in session 1, and the call to daemon() doesn't put the caller into that session.

If inetd is a self-attached entity, you don't need to specify the -D option because the HAM automatically switches to monitoring the new process that daemon() creates.

When inetd dies, all the actions associated with a death condition under it are executed:

# slay inetd

# cat /proc/ham/inetd/.info
Path            : inetd
Entity Pid      : 11071511  <- new pid of entity
Num conditions  : 1
Entity type     : ATTACHED
Stats:
Created         : 2001/08/30 23:04:49:930148650
Last Death      : 2001/08/30 23:10:31:889820814
Restarted       : 2001/08/30 23:10:31:904818519
Num Restarts    : 1

As you can see, the statistics relating to the entity inetd are updated.

Similarly, if a HAM itself is terminated, the Guardian takes over as the new HAM, and creates a Guardian for itself.

# cat /proc/ham/.info
Ham Pid            : 10993674  <----- This is the HAM
Guardian Pid       : 10997782  <----- This is the Guardian
Ham Failures       : 0
Guardian Failures  : 0
Num Entities       : 1
Num Conditions     : 1
Num Actions        : 1

... Kill the ham ....

# /bin/kill -9 10993674        <---- Simulate failure

... re-read the stats ...

# cat /proc/ham/.info  
Ham Pid            : 10997782  <----- This is the new HAM
Guardian Pid       : 11124746  <----- This is the Guardian
Ham Failures       : 1
Guardian Failures  : 0
Num Entities       : 1
Num Conditions     : 1
Num Actions        : 1

As you can see, the old Guardian is now the new HAM, and a new Guardian has been created. All entities and conditions remain as before; the monitoring continues as usual. The HAM and the Guardian ignore all signals that they can.