------------------------------
                   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:
ipmiutil       - a meta command for all the below command functions
isel           - show the firmware System Event Log records
ilan           - 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
iserial        - show and configure the serial port for BMC access
ifru           - show decoded FRU board/product info, write FRU asset tag
ireset         - to cause the BMC to hard reset the system
isensor        - show the sensor data records and fru data.
ialarms        - show/set the Telco alarms 
iwdt           - show/set the watchdog timer via IPMI
checksel       - script using showsel to check the SEL, write to syslog, and 
	         clear the SEL if needed.
isel.8         - man page for showsel
ilan.8         - man page for pefconfig
iserial.8      - man page for tmconfig
ifru.8         - man page for fruconfig
ireset.8       - man page for hwreset
isensor.8      - man page for sensor
ialarms.8      - man page for alarms
iwdt.8         - man page for wdt
COPYING        - BSD License for copying 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).
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 IPMI Management Utilities currently work with platforms that 
support the IPMI 1.5 or 2.0 specification.   IPMI servers can be managed 
locally, or remotely via IPMI LAN, even when the OS or main CPU is not 
functional.

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 ipmiutil utilities will use an IPMI Driver, either the Intel IPMI package
(ipmidrvr, /dev/imb), MontaVista OpenIPMI (/dev/ipmi0), the valinux IPMI 
Driver (/dev/ipmikcs), the LANDesk ldipmi daemon, or the GNU FreeIPMI 
library (libfreeipmi.so.0).  The ipmiutil utilities can also use direct
user-space I/Os in Linux or FreeBSD if no IPMI driver is detected.

If ipmiutil is compiled with LANPLUS enabled, then it does depend upon
libcrypto.so, which is provided by the openssl package.

------------------------
   Build Instructions
------------------------

See notes in the INSTALL file from the ipmiutil*.tar.gz archive.

------------------------
   IPMI Configuration
------------------------
See http://ipmiutil.sourceforge.net/docs/UserGuide

Note that ipmiutil can autodetect the IPMI interface using SMBIOS/dmi 
and use driverless KCS or SSIF if no IPMI driver is loaded.

For some IPMI systems, a minimum firmware version may be needed to 
support all features.  On an Intel TSRLT2 system, for instance, it
requires BMC Firmware version 54 or greater.

The 'ipmiutil lan' utility can be used to easily set up a working 
configuration of BMC LAN, SOL, and PEF Alerting while Linux is running,  
instead of a series of 40-50 commands with ipmitool, or a proprietary
vendor tool, which may even require booting to DOS.

The ipmiutil package does not set the panic timeout.
If a specific panic timeout is desired, do 
"echo 10 >/proc/sys/kernel/panic" to set it to 10 seconds, for instance.
or add panic=10 to the kernel line in grub.conf.

The bmc_panic patch has been obsoleted by the CONFIG_IPMI_PANIC option
in the OpenIPMI driver, which is included in kernel.org.
The bmc_panic functionality is also included in the Intel imb IPMI driver
build 28 and greater.
To apply the bmc_panic patch (in kern/) to a different 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

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

Contact for best-effort support: arcress at users.sourceforge.net or 
ipmiutil-developers at lists.sourceforge.net or http://ipmiutil.sf.net

--------------------
  LICENSING:
--------------------
The BSD License in the COPYING file applies to all source files 
herein, except for 
  * util/md5.c (Aladdin unrestricted license, compatible with BSD) 
  * util/md2.h (GPL)
  * util/ipmi_ioctls.h (GPL)
While the BSD License allows code reuse in both open and non-open 
applications, the md2.h and ipmi_ioctls.h files would have to be removed 
if used in a non-open application.  There is a ALLOW_GPL compile flag
for this that is disabled by default, but can be enabled for open-source
by running "./configure --enable-gpl". 

--------------------
  CHANGE HISTORY:
--------------------
See http://ipmiutil.sourceforge.net/docs/ChangeLog