
This is an implementation of the Service Availability Forum's 
Hardware Platform Interface SNMP sub-agent.

Through this subagent one can includes support for multiple different 
types of hardware including: IPMI, IBM Blade Center (via SNMP), 
Linux Watchdog devices, and Sysfs based systems.

---------------------------------------------------------
PREREQUISITES
---------------------------------------------------------
The following software is required to build openhpi

any HPI 1.0 implementation that is based on SAF specification 
	SAI-HPI-A.01.01. Recommended: openhpi >= 0.4
autoconf >= 2.50
automake >= 1.5
net-snmp >= 5.0.8
	(Don't use earlier versions - the AgentX protocol had some
	 serious issues).
	(Don't use 5.0.7 - it has a bug in the CONTAINER operations that 
	 seg faults the sub-agent).
GLIB-1.2	(note we may be switching to 2.0 in the next release)

---------------------------------------------------------
BUILD / INSTALLATION
---------------------------------------------------------
First time to extract the code:
run ./boostrap

This will generate all files needed to compile.

after running the bootstrap script, run:
	./configure

then make (or make rpm)
and then (as root or with proper system install permissions)
	make install (or install from the rpm).

It will generate the subagent code and put the configuration file 
- hpiSubagent.conf in the NetSNMP configuration directory.

If you want to generate the guide, run:
        make pdf-m

in the docs directory.
---------------------------------------------------------
RUNNING
---------------------------------------------------------

1. Configure your OpenHPI installation to work. Make sure that 
   /etc/openhpi/openhpi.conf lists the desired plugin.

2. Configure your NetSNMP configuration file (snmpd.conf) to include
   "master  agentx"

3. Start the NetSNMP daemon. (usually /etc/init.d/snmpd on various Linux distros).

4. Start the hpiSubagent. (either use the runtime script: /etc/init.d/openhpi-subagent,
   or just run it from the terminal).  You should see something similar in the
   syslog log file - /var/log/messages:

   ...
   Feb  6 10:53:37 konrad hpiSubagent[9890]: Not sending events during startup.
   Feb  6 10:53:37 konrad hpiSubagent[9890]: Checking HPI infrastructure every 4 seconds.
   Feb  6 10:53:37 konrad hpiSubagent[9890]: Max Event rows 1024.
   ...

5. Browse the MIB tree. When browsing the MIB tree, make sure you 
   load the MIB in your favorite SNMP browser. If you are using 
   NetSNMP commands, set the MIBS environment variable to ALL:

   $export MIBS=ALL
  
   And set the MIBDIRS enviroment variable to point to the the directory where the 
   OpenHPI MIB file is located (usr/share/doc/openhpi-subagent-0.2/mib) or
   copy the MIB file in to the NetSNMP MIB default directory (usually 
   /usr/share/snmp/mibs). To set the MIBDIRS, refer to 'man snmpcmd' or:

   $export MIBDIRS=+/usr/share/doc/openhpi-subagent-0.2/mibs

   After these step you should have no trouble browsing the HPI MIB:

   $snmpwalk -v2c -c public localhost hpi
   HPI-MIB::saHpiEntryCount.0 = Counter32: 3
   HPI-MIB::saHpiEntryUpdateCount.0 = Gauge32: 3
   HPI-MIB::saHpiEntryUpdateTimestamp.0 = Counter64: 1076082821603968000
   HPI-MIB::saHpiDomainID.0.1.1 = Gauge32: 0
   HPI-MIB::saHpiDomainID.0.2.2 = Gauge32: 0
   HPI-MIB::saHpiDomainID.0.3.3 = Gauge32: 0
   HPI-MIB::saHpiEntryID.0.1.1 = Gauge32: 1
   HPI-MIB::saHpiEntryID.0.2.2 = Gauge32: 2
   HPI-MIB::saHpiEntryID.0.3.3 = Gauge32: 3
   HPI-MIB::saHpiResourceID.0.1.1 = Gauge32: 1
   HPI-MIB::saHpiResourceID.0.2.2 = Gauge32: 2
   HPI-MIB::saHpiResourceID.0.3.3 = Gauge32: 3
   HPI-MIB::saHpiResourceEntityPath.0.1.1 = STRING: "{ROOT,0}{SYSTEM_CHASSIS,1}{SYSTEM_BOARD,1}"
   HPI-MIB::saHpiResourceEntityPath.0.2.2 = STRING: "{ROOT,0}{SYSTEM_CHASSIS,1}{POWER_SUPPLY,1}"
   ....

6). If you want to receive traps make sure you are running a SNMP trap daemon
    (NetSNMP provides one - snmptrapd). 
    Furthermore make sure that the SNMP daemon is configured to send traps 
    and specify its destination, such as:
    "inform2sink <hostname>" in snmpd.conf.
    Refer to 'man snmpd.conf' for more details.

---------------------------------------------------------
CLEANUP
---------------------------------------------------------
To remove the temporary build files, type:

make clean

If you are a maintainer, and need to remove all autogenerated files, type:

make clean
make maintainer-clean


---------------------------------------------------------
GENERAL RELEASE NOTES and WHAT'S NEW
---------------------------------------------------------

* Second release of the HPI SNMP sub-agent. 

* Support for full implementation of the HPI-MIB v1.4
  (included). This means HPI 1.0 instrumentation using 
  HPI-MIB objects in twenty-three tables:
	- Resource Presence Table entities,
		- HotSwap capabilities,
	- Resource Data Records,
		- Sensors
		    - Current sensor reading,
		    - Reading values for 
			 - Max,
			 - Min, 
			 - Nominal, 
			 - Normal maximum, 
			 - Normal minimum
		    - Threshold values for:
			- Upper Critical,
			- Upper Major,
			- Upper Minor,
			- Lower Critical,
			- Lower Major,
			- Lower Minor,
			- Positive Hysteresis,
			- Negativie Hysteresis	
		- Inventory,
		- Control,
		- Watchdog
	- Events and System Event Log

* SGML Guide for writing a sub-agent using NetSNMP API, titled:
  "NetSNMP subagent development manual."

* Support for notifications/TRAPS as defined in the MIB:
	- For Events:
		- Sensor,
		- Hot Swap,
		- Watchdog,
		- OEM,
		- User
	- For Resource Data Records,
	- For Resource Presence Table

* Support for user configurable options:
	 - update timer for new RPT/RDR/Events ,
	 - maximum events held in eventw row before they are
	   automatically removed,
	 - sending of new found RPT/RDR/Events during startup.

* Example code for retrieving instrumentation information
  using SNMP.

* Fix many bugs:
    852223      Definition Conflicts between net-snmp-config.h and config.h
    861785      missing release files in agent
    861788      basics.sgml lacks formatting
    872434      Ugly hexidecimal string in HPI-MIB::saHpiSystemEventLogOemEv
    872437      segfault when populating inventory entries using snmp_bc
    872580      Duplicate items are added in all the tables, except one
    873853      Change the 'hpi' OID from experimental to what SAF ratified
    873854      Make the 'saHpiSystemEventDelete' and 'saHpiEventDelete' wrt
    873961      Duplicate control, inventory, sensor, and watchdog tables.
    876161      Memory consumption > 64MB after 3 days and grows.
    876166      Too many sensors, control, inventory objects.
    876241      The saHpiCtrlState OBJECT in the MIB defines wrong length ..
    876243      saHpiCtrlState object for type analog in description mention
    876290      The 'SaHpiCtrlAttributes' is missing info about Analog type.
    876402      saHpiCtrlBool should have a better name, like SaHpiCtrlIgnor
    876405      saHpiCtrlAttributes for the type 'stream' is missing data.
    876446      The description in the SaHpiCtrlAttributes is confusing.
    876904      Missing Data Configuration elements
    877063      consolodate ..StateCategoryXXXX fields
    878592      hpiSubagent: SEGMENT FAULT with latest code
    885081      +1 for all enumerated objects in the MIB.
    887238      The saHpiInventoryTable is missing an object.
    887240      saHpiInventoryAttributes is missing information about Oem ty
    892911      If no startup events is selected, the SNMP daemon never
    893138      The syslog logging needs to have more information.
    893142      snmpd: send_trap: Unknown PDU type
    894664      Missing OEM variable for rdr inventory type
    904673      Add Sensor Readings Flags to saHpiSensorEntry
    908543      Add IsThreshold OID to saHpiSensroEntry	
    908544      Add TholdCapabilities OID to saHpiSensorEntry
    907712      Problems with SNMP agent & ipmidirect plugin
    908561      Common sense checks missing

Consult the ChangeLog for more details.

---------------------------------------------------------
FOR MORE INFO
---------------------------------------------------------

For more information please see the project website at 
http://openhpi.sourceforge.net

Also visit SAForum's website at http://www.saforum.org


---------------------------------------------------------
BUGS
---------------------------------------------------------

If you have any bugs, issues, please visit the project
website http://openhpi.sourceforge.net, or visit us
in the #openhpi channel on FreeNode and OFTN network.


---------------------------------------------------------
DEFINES
---------------------------------------------------------

There is one #define declaration that you can enable during 
compilation time. Refer to bug [ 876304 ] Make the MIB Sensor 
reading return dynamic data, for more concrete information. 
It basicly boils down to querying the 
HPI-MIB::saHpiSensorReadingCurrentInterpreted
table and getting the results instantly instead of waiting for
the HPI Sub-agent to refresh its internal data per 
"check_hpi_interval"  configuration option. Use 
-DGET_ROUTINE_CALLS_SNMP_GET to enable this option. Be aware that 
it does not work with the SNMP_BC plugin.
