
             ------------------------------
                   ipmiutil README
	       IPMI Management Utilities
             ------------------------------

The ipmiutil utilities below allow the user to access the firmware System 
Event Log and configure the Platform Event Filter table for the new OS 
Critical Stop records.

The following files are included in the install:
showsel        - show the firmware System Event Log records
pefconfig      - show and configure the Platform Event Filter table
                 to allow BMC LAN alerts from OS Critical Stop messages, 
                 also shows and sets the BMC LAN configuration parameters
tmconfig       - show and configure the serial port for BMC access
fruconfig      - show decoded FRU board/product info, write FRU asset tag
hwreset        - to cause the BMC to hard reset the system
sensor         - show the sensor data records and fru data.
alarms         - show/set the Telco alarms 
wdt            - show/set the watchdog timer via IPMI
checksel       - script using showsel to check the SEL, write to syslog, and 
	         clear the SEL if needed.
showsel.8      - man page for showsel
pefconfig.8    - man page for pefconfig
tmconfig.8     - man page for tmconfig
fruconfig.8    - man page for fruconfig
hwreset.8      - man page for hwreset
sensor.8       - man page for sensor
alarms.8       - man page for alarms
wdt.8          - man page for wdt
COPYING        - BSD License for coping ipmiutil utilities
README         - ReadMe for ipmiutil utilities
UserGuide      - User Guide for ipmiutil utilities

Other files in the project:
kern/bmc_panic*.patch - The panic handler module to write to the SEL & other 
		stuff (part of the kernel, now merged with OpenIPMI driver).
freeipmi/libfreeipmi.so - GNU FreeIPMI library ver 0.1.0, from 
			  http://www.gnu.org/software/freeipmi/
doc/bmclanaol.mib     - SNMP MIB for BMC LAN Alert-Over-Lan traps
doc/bmclanpet.mib     - SNMP MIB for BMC LAN Platform Event Traps
test/*.sh             - Some unit test scripts for ipmiutil/panicsel
test/dopanic.c        - sample kernel module to cause a Linux panic

--------------------
   Dependencies:
--------------------
The ipmiutil utilities require an IPMI Driver, either the Intel IPMI package
(ipmidrvr, /dev/imb), MontaVista OpenIPMI (/dev/ipmi0), the valinux IPMI 
Driver (/dev/ipmikcs), or the GNU FreeIPMI library (libfreeipmi.so.0). 

The IPMI 1.5 spec, Table 36-3 defines the sensor types for SEL records, 
as used by showsel.
The IPMI 1.5 spec, Table 15-2 defines the Platform Event Filter table
entries, as used by pefconfig.
The IPMI 1.5 spec, Table 19-4 defines the LAN Configuration Parameters,
as used by pefconfig.

The IPMI Management Utilities currently work with platforms that 
support the IPMI standard.  If the platform does not support IPMI, these 
changes are inert, but the code could be modified for another system 
management interface.  The Service Availability Forum is working on an 
umbrella API that could be used to group IPMI and other system management 
interfaces under a meta-standard.  When this becomes available, these 
Panic Handler Enhancements will conform to that API so that non-IPMI 
platforms can be integrated more easily.

Support for the LanDesk IPMI driver requires a library supplied by 
LanDesk (libipmiapi.a).  After obtaining this library, place it in
freeipmi/libipmiapi.a.  Then you can link ipmiutil to support it by 
modifying util/Makefile.am and uncommenting the lines with 
-DLINK_LANDESK and -lipmiapi.

--------------------
   Configuration
--------------------
To find the base address of the IPMI KCS interface, or to find the IPMI
SMBus slave address, you can use the 'dmidecode' utility provided with
some Linux distributions.  See also http://www.nongnu.org/dmidecode/.

For some IPMI systems, a minimum firmware version may be needed to 
support this feature.  On an Intel TSRLT2 system, for instance, these are 
the minimum levels:
  BMC Firmware ver 54 or greater
  SSU ver 2.RC.1 or greater (if SSU is used instead of pefconfig)

The pefconfig utility can be used instead of SSU to configure the BMC LAN
Alerting while Linux is running.  The ipmiutil rpm runs pefconfig during
the rpm installation. 

By default, the ipmiutil rpm does not set the panic timeout.
If a different panic timeout is desired, do 
"echo 10 >/proc/sys/kernel/panic" to set it to 10 seconds, for instance.

To apply the bmc_panic patch (in kern/) to a new version of kernel source:
   kver=2.4.18
   cd /usr/src/linux-${kver}
   cat bmcpanic-${kver}.patch | patch -p1
   make menuconfig     (make sure CONFIG_BMCPANIC=y)
   make oldconfig
   make dep
   make bzImage
   make modules
   make modules_install
   mkinitrd -f /boot/initrd-${kver}.img ${kver}
   make install
   reboot

Steps to set up BMC LAN Alerts manually with SSU:
  Boot to the service partition and select SSU.
  Select LAN Alerting
  Select BMC LAN button
  Click the Enable LAN Alerts checkbox
  Set "always available"
  Set the SNMP community to "public"
  Set the IP address, gateway, net mask, and the Alert IP addres.
  Select Options/Event Filtering
  Enable all of the events in the list (<<)
  Close Event Filtering.
  File/Save the LAN Alert config
  Exit SSU
  
  Reboot
  Install the ipmiutil rpm from Linux, which runs "pefconfig", 
  which is still needed to set up the new PEF table entry 
  (it can also set BMC LAN).

------------------------------
   KNOWN PROBLEMS
------------------------------

The GNU FreeIPMI KCS library does not handle FRU requests for 
devices not subordinate to the BMC, i.e. addresses other than 0x20.
This causes the HSC to return the FRU data from the BMC baseboard.
If another IPMI driver is used, this works ok.

Contact for best-effort support: arcress@users.sourceforge.net

--------------------
  CHANGE HISTORY:
--------------------
  (See the ChangeLog file)
