
		         IPMI UTILITIES AND 
                   LINUX PANIC HANDLER ENHANCEMENTS 
                            USER GUIDE 

------------------------
   CONTENTS
------------------------
1.0  Overview
2.0  Dependencies
   2.1  Configuration
   2.2  References
3.0  Utility Man Pages
   3.1	showsel
   3.2	hwreset
   3.3	sensor
   3.4	pefconfig
   3.5	tmconfig
   3.6	fruconfig
   3.7	alarms
   3.8	wdt
   3.9	icmd
4.0  Use Cases
   4.1  Usage of IPMI utilities for sensor thresholds
   4.2  Usage of IPMI utilities for BMC LAN configuration 
   4.3  Usage of IPMI utilities to set watchdog timer
   4.4  Usage of kernel panic handler code 
   4.5  Interpreting BMC LAN SNMP Traps from Platform Events 
5.0  IPMI Utilities on Windows
6.0  Problems
7.0  Related Information

------------------------
1.0  OVERVIEW
------------------------

This feature includes both IPMI utilities and a kernel patch for 
panic handler enhancements.

The ipmiutil IPMI 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, as well as other common IPMI system management
functions.  

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       - to set up the BMC Serial port for various modes, such as
                 Terminal Mode.  
fruconfig      - show the FRU chassis, board, and product data, and 
                 optionally write an asset tag to the FRU product area.
hwreset        - to cause the BMC to hard reset the system    
sensor         - show all Sensor Data Records and full sensor readings
alarms	       - show and set alarm indicators
wdt	       - show and set watchdog timer parameters
icmd           - send specific IPMI commands to the BMC,
                 mainly for testing and debug purposes.

Other supporting files:
checksel       = script using showsel to check the SEL, write new events
                 to the syslog, and clear the SEL if nearly full.
bmclanpet.mib  = SNMP MIB for BMC LAN Platform Event Traps
bmclanaol.mib  = SNMP MIB for BMC LAN Alert-Over-Lan traps
libfreeipmi.so = GNU FreeIPMI library, see http://www.gnu.org/software/freeipmi
kern/*         = kernel patches for panic handling
test/*         = scripts and utilities used in testing ipmiutil/panicsel

The kernel panic handler patch (bmcpanic.patch) adds additional 
features to the Linux Panic Handler so that more information can be 
saved and passed along if a Linux panic condition occurs.  
bmc_panic features:

 1. Write an OS Critical Stop event to firmware System Event Log (SEL)
    This is in bmcpanic.patch and in OpenIPMI.
 2. Send SNMP trap via BMC LAN Alerting mechanism
    Accomplished by configuring the BMC with 'pefconfig'.
 3. Turn on the Critical Alarm LED on the Telco Alarms Panel
    This is in bmcpanic.patch, but not in OpenIPMI due to 
    platform-specific issues with the alarms panel.

The kernel portion of this, except item 3, is now included in the OpenIPMI
project with the CONFIG_IPMI_PANIC_EVENT option, and the OpenIPMI
driver has merged into Linux kernel 2.4.21 and beyond.
The latest version of the OpenIPMI driver can be obtained from
http://openipmi.sourceforge.net.

------------------------
2.0  DEPENDENCIES
------------------------

The IPMI Utilities will run on both Linux and Windows, and should be
portable to other OSs, if an IPMI driver can be obtained.

The IPMI Utilities and Panic Handler Enhancements currently work with 
platforms that support the IPMI standard.  If the platform does not 
support IPMI, these changes are inert.  The Service Availability Forum 
has developed a Hardware Platform Interface (HPI) specification that 
can be used to group IPMI and other system management interfaces 
together.  A set of comparable HPI utilities is included in the 
ipmiutil project source as hpiutil/*.

The Panic Handler kernel enhancements (bmcpanic.patch) are now 
included in the OpenIPMI driver via the CONFIG_IPMI_PANIC_EVENT 
and CONFIG_IPMI_PANIC_STRING parameters in the kernel config file 
(/usr/src/linux/.config), assuming kernel 2.4.21 or greater. 

The ipmiutil utilities require an IPMI Driver, either the MontaVista 
OpenIPMI driver (/dev/ipmi0), Intel IPMI package (ipmidrvr /dev/imb),
the valinux IPMI Driver (/dev/ipmikcs), or the GNU FreeIPMI library 
(/usr/lib/freeipmi.so.0).
See http://openipmi.sourceforge.net for the OpenIPMI driver.
See http://downloadfinder.intel.com/scripts-df/Product_Search.asp?Prod_nm=ipmi*driver*source  for Intel IMB driver
See http://cvs.sf.net/cgi-bin/viewcvs.cgi/ipmitools/ipmitools/kernel/kcs/patches/2.4.x/ for the valinux driver.
See http://www.gnu.org/software/freeipmi/ for GNU FreeIPMI.
 
Each of the IPMI management utilities will detect which IPMI driver is
present, and if none are found, it will attempt to use the FreeIPMI 
library for local KCS access, or for LAN access.  A pre-built 
version of FreeIPMI 0.1.0 is included with the ipmiutil rpm.

------------------------
2.1  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 the BMC LAN/PEF 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)
IPMI systems prior to version 1.5 do not support BMC LAN or PEF features.

The pefconfig utility can be used instead of SSU to configure the BMC LAN 
Alerting while the OS is running.  The ipmiutil rpm runs pefconfig during
the rpm installation.
 
By default, the ipmiutil IPMI utilities rpm does not set the panic timeout.
If a different panic timeout is desired, add 'append="panic=10"' in lilo.conf, 
or do "echo 10 >/proc/sys/kernel/panic" in one of the /etc/init.d scripts to 
set it to 10 seconds, for instance.  

The tmconfig utility is intended to configure the EMP serial port on the 
server for shared access between BMC/IPMI functions and BIOS Console 
Redirection.  Some platforms only support only Basic Mode for BMC/IPMI 
functions.  Basic Mode requires a remote client application to utilize it 
(Windows ISC Console/DPC applet, or a special modified Linux telnet).  
There are some platforms which implement Terminal Mode via IPMI v1.5 
Appendix E to make remote management with character commands available
on the serial port without a special remote client application.

Note that the checksel script will be copied to /etc/cron.daily when 
the Linux rpm is installed, so that showsel will automatically save 
SEL records to syslog and clear the SEL if it gets nearly full.  If 
you do not want this to happen automatically, remove the checksel 
script from the /etc/cron.daily directory.

------------------------
2.2  REFERENCES
------------------------

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 enterprises.3183 SNMP traps come from the BMC firmware, and are defined in 
bmclan*.mib files in the ipmiutil project.  Details about the format of these
Platform Event Traps are available in section 12.2 through 12.5 of the ISM 
(Intel Server Management) 5.x Technical Product Specification at 
http://www.intel.com/support/motherboards/server/isc/sb/cs-008024.htm

The enterprises.343 SNMP traps come from ISM and are defined in mapbase*.mib 
files on the platform CD.
The enterprises.412 SNMP traps come from ISM/DMTF, defined in dmtf*.mib files 
on the platform CD.

------------------------
3.0  UTILITY MAN PAGES
------------------------

3.1 SHOWSEL(8)                                             SHOWSEL(8)
 
NAME
       showsel - show firmware System Event Log records
 
SYNOPSIS
       showsel [-cswvx -N node -R pswd ]
 
DESCRIPTION
       showsel  is  a  program that uses IPMI commands to to read
       and display the System Event Log (SEL) which is stored  by
       the  BMC  firmware.  IPMI commands are issued to read each
       record, and, if  specified,  incrementally  write  records
       that  have  not previously been read into the Linux syslog
       (/var/log/messages).  This  utility  can  use  either  the
       /dev/ipmi0  driver  from  MontaVista,  the /dev/imb driver
       from Intel, the /dev/ipmikcs driver from valinux,  or  the
       GNU FreeIPMI library.
 
OPTIONS
       Command line options are described below.        
 
       -c     Clears the SEL of all records.  If the SEL  becomes
              full  (free  space  =  0), it no longer accepts new
              records, so the SEL should be cleared periodically.
 
       -s     By  default,  all  SEL records are displayed.  This
              option causes only the records with  sensor_type  =
              0x20 (OS Critical Stop) to be displayed.
 
       -w     This  option writes SEL records to the Linux syslog
              (/var/log/messages) or Windows Application Log.  It
              only writes SEL records that have timestamps  newer
              than  the  last record written to syslog.  It saves
              the  last  timestamp  in  an   index   file   named
              /usr/share/ipmiutil/sel.idx (.\sel.idx in Windows).
 
       -v     Only  show  the  version  information.  This shows:
              the showsel utility version, the BMC  version,  the
              IPMI  version,  the  SEL version, and the amount of
              free space in the SEL.
 
       -x     Causes extra debug messages to be displayed.

       -N nodename
              Nodename  of  the remote target system.  If a node-
              name is specified,  IPMI  LAN  interface  is  used.
              Otherwise  the local system management interface is
              used.
 
       -R rmt_pswd
              Remote  password  for  the  nodename  given.    The
	      default is a null password. 

SEE ALSO
       pefconfig(8)
 
WARNINGS
       See http://ipmiutil.sourceforge.net/ for the  latest  ver
       sion of showsel and any bug fix list. 


3.2 HWRESET(8)                                             HWRESET(8)
 
NAME
       hwreset - perform a hardware reset on the system
 
SYNOPSIS
       hwreset [-dcnorsx -N node -R pswd]
 
DESCRIPTION
       hwreset  is a program that uses IPMI commands to perform a
       hardware reset of  the  chassis.   This  utility  can  use
       either the /dev/ipmi0 driver from MontaVista, the /dev/imb
       driver from Intel, or the /dev/ipmikcs  driver  from  val
       inux.
 
OPTIONS
       Command line options are described below.
 
       -c     Power Cycle the system chassis
 
       -d     Power Down the system chassis

       -n     Send NMI to the system
 
       -o     Do a soft shutdown of the OS
 
       -r     Hard Reset the system chassis (default action)
 
       -s     Reset and boot to the Service Partition
 
       -x     Causes extra debug messages to be displayed.

       -N nodename
              Nodename  of  the remote target system.  If a node-
              name is specified,  IPMI  LAN  interface  is  used.
              Otherwise  the local system management interface is
              used.
 
       -R rmt_pswd
              Remote  password  for  the  nodename  given.    The
	      default is a null password. 
 
SEE ALSO
       showsel(8)
 
WARNINGS
       See  http://ipmiutil.sourceforge.net/  for the latest ver
       sion of hwreset and any bug fix list.


3.3 SENSOR(8)                                               SENSOR(8)
 
NAME
       sensor - show Sensor Data Records
 
SYNOPSIS
       sensor [-stx -n num -h val -l val -N node -R pswd]
 
DESCRIPTION
       sensor  is  a  program that uses IPMI commands to show and
       decode Sensor Data Records and current sensor readings for
       all   sensors  in  the  system.   The  readings  are  only
       retrieved for Full SDR  records.   This  utility  can  use
       either the /dev/ipmi0 driver from MontaVista, the /dev/imb
       driver from Intel, or the /dev/ipmikcs  driver  from  val-
       inux.
 
       Note that this utility currently only displays Sensor Data
       Records reported by from the BMC  chipset.   Some  systems
       may  have  other devices with sensors that are also avail-
       able via IPMI.

OPTIONS
       Command line options are described below.
 
       -h val High threshold value to set for the specified  sen-
              sor.   This  val  can be in decimal, or of the form
              0x1a, to match the value shown by sensor  following
              the " = ".
 
       -l val Low  threshold  value to set for the specified sen-
              sor.  This val can be in decimal, or  of  the  form
              0x1a,  to match the value shown by sensor following
              the " = ".
 
       -n num Number of the sensor to set.  This num  can  be  in
              decimal,  or  of  the form 0x1a, to match the value
              shown by sensor following the "sensor: 20 ".
 
       -s     Show sensor list in a simpler format without  unin-
              terpreted binary values.
 
       -t     Show any thresholds for each sensor also.
 
       -x     Causes eXtra debug messages to be displayed.

       -N nodename
              Nodename  of  the remote target system.  If a node-
              name is specified,  IPMI  LAN  interface  is  used.
              Otherwise  the local system management interface is
              used.
 
       -R rmt_pswd
              Remote  password  for  the  nodename  given.    The
              default is a null password.

SEE ALSO
       showsel(8)
 
WARNINGS
       See  http://ipmiutil.sourceforge.net/  for the latest ver-
       sion of sensor and any bug fix list.


3.4 PEFCONFIG(8)                                         PEFCONFIG(8)

NAME
       pefconfig  - show and configure BMC LAN parameters and set
       up a PEF entry to send BMC LAN Alerts for OS Critical Stop
       log events
 
SYNOPSIS
       pefconfig [-dersx -n pefnum -i eth1 ]
                     [-I ipadr -M macadr -S subnet]
                     [-G gwyip -H gwymac -P password ]
                     [-A alertip -B alertmac -C community ]
		     [-N nodename -R rmt_node_pswd ]
                     [-L lan_channel_num ]
 
DESCRIPTION
       pefconfig  is  a  program that uses an IPMI driver to send
       IPMI commands which configure a new Platform Event  Filter
       table  entry  for  an OS Critical Stop (0x20) SEL firmware
       log event, so that it will be enabled to send  a  BMC  LAN
       Alert.   This  utility  also  sets  up  all of the BMC LAN
       Parameters to enable sending the BMC LAN Alerts.   The  IP
       address  and  MAC address of the local system, the default
       gateway, and the alert destination  can  be  defaulted  to
       those  specified  in  Linux,  or can be overridden by user
       parameters.  This utility can use  either  the  /dev/ipmi0
       driver  from  MontaVista,  the /dev/imb driver from Intel,
       the /dev/ipmikcs driver from valinux, or the GNU  FreeIPMI
       library.   This  utility is designed to be used on systems
       with IPMI 1.5 or greater in order to support PEF  records.
 
OPTIONS
       Command line options are described below.  Note that with
       out  options, pefconfig behaves as if option -e were used.
       To just read the configuration, use option -r.
 
       -d     This option disables the PEF entries, so as not  to
              send BMC LAN alerts.
 
       -e     This  option  enables the BMC LAN configuration and
              PEF events.  The utility will attempt to obtain the
              default  BMC  LAN  parameters from the OS automati
              cally,  or  they  can  be  specified  with  command
              options below.
 
       -i ethif
             By  default,  the eth0 interface is used to find IP
              and MAC addresses.  Sometimes, however,  the  first
              ethernet  port  on the baseboard may be represented
              by Linux as eth1 or eth2 instead.  If so, use  this
              option  to  indicate the correct ethernet interface
              to use.  By default, pefconfig will scan up  to  32
              eth  interfaces  for  the  onboard one that BMC LAN
              uses.
 
       -n num By default, the new PEF entry for OS Critical  Stop
              is  inserted at offset 12 into the table.  This can
              be changed to insert  it  at  an  offset  >  12  if
              another entry already exists at offset 12.
 
       -r     This  option  just  reads the configuration without
              writing any BMC LAN parameters or writing  any  new
              entries to the PEF table.
 
       -s     This  option  will  also display some of the Serial
              parameters.
 
       -x     Causes extra debug messages to be displayed.

       -D     This causes the local IP address to  be  determined
              by DHCP instead of a static IP address.
 
       -I ip_addr
              This  specifies the local IP address to use for the
              BMC LAN on eth0.  The default is  to  automatically
              obtain this from the Linux ifconfig.
 
       -M mac_addr
              This specifies the local MAC address to use for the
	      BMC  LAN  on  eth0.   The  format  can  be   either
              11:22:33:44:55:66    or   11-22-33-44-55-66.    The
              default is to automatically obtain  this  from  the
              Linux ifconfig.
 
       -S subnet
              This specifies the local subnet mask to use for the
              BMC LAN on eth0.  The default is  to  automatically
              obtain this from the Linux ifconfig.
 
       -G gwy_ip_addr
              This  specifies  the  default gateway IP address to
              use for the BMC LAN.  The default is  to  automati
              cally obtain this from the Linux route table.

       -H gwy_mac_addr
              This specifies the default gateway's MAC address to
              use for the BMC LAN.   The  format  can  be  either
              11:22:33:44:55:66    or   11-22-33-44-55-66.    The
              default is to automatically obtain  this  from  the
              Linux arp cache.
 
       -A alert_ip_addr
              This   specifies  the  SNMP  Alert  Destination  IP
              address to use for the BMC LAN.  By  default,  this
              utility  will  attempt  to  obtain  this  from  the
              /etc/snmp/snmpd.conf file, via the trapsink parame
              ter.   The  alert  destination will see the BMC LAN
              traps with the  enterprises.3183.1.1  OID.   If  no
              alert  IP address is specified in either snmpd.conf
              or this parameter, or if that IP address  does  not
              respond, the other SNMP parameters for BMC LAN will
              be skipped.
 
       -B alert_mac_addr
              This specifies the SNMP  Alert  Destinations's  MAC
              address  to use for the BMC LAN.  The format can be
              either 11:22:33:44:55:66 or 11-22-33-44-55-66.  The
              default is to attempt to obtain this from the Linux
              arp cache.  This parameter is ignored if  there  is
              no Alert IP address.

       -C snmp_community
              This specifies the SNMP Community name to  use  for
              BMC  LAN  Alerts.   The default community string is
              "public".  This parameter is ignored if there is no
              Alert IP address.
 
       -P password
              This specifies the firmware password to use for BMC
              LAN access.  If not specified, the user  and  pass
              word configuration will not be changed.
 
       -L lan_ch_num
              This specifies the IPMI LAN channel number used for
              BMC LAN.  This varies by platform, and can be found
              in   the  platform  technical  specifications.   By
              default, pefconfig scans all IPMI channels to  find
              a LAN channel for BMC LAN.

       -N nodename
              Nodename of the remote target system.  If  a  node-
              name  is  specified,  IPMI  LAN  interface is used.
              Otherwise the local system management interface  is
              used.
 
       -R rmt_pswd
              Remote   password  for  the  nodename  given.   The
              default is a null password.
 
SEE ALSO
       showsel(8) tmconfig(8)

WARNINGS
       See http://ipmiutil.sourceforge.net/ for the  latest  ver
       sion of pefconfig and any bug fix list.


3.5 TMCONFIG(8)                                           TMCONFIG(8)
 
TMCONFIG(8)                                           TMCONFIG(8)
 
NAME
       tmconfig  -  configure  a system for Serial/EMP management
       functions, such as Terminal Mode, and optionally share the
       port with the Serial Console.
 
SYNOPSIS
       tmconfig [-bclrsx -m0 -m1 -n ser_chan -u user -p passwd -N
       node -R pswd]
 
DESCRIPTION
       tmconfig is a program that uses an  IPMI  driver  to  send
       IPMI   commands   which   configure  a  system  to  enable
       EMP/serial Terminal Mode management functions  within  the
       firmware,  so  that  an administrator can use command-line
       character commands via the serial port to power cycle  the
       system  and perform other functions, even if the system is
       not running an OS.  This level of access needs to be  pro
       tected  by  a username/password login, which can be speci
       fied with this utility.  This utility can use  either  the
       /dev/ipmi0  driver  from  MontaVista,  the /dev/imb driver
       from Intel, the /dev/ipmikcs driver from valinux,  or  the
       GNU FreeIPMI library.
 
OPTIONS
       Command line options are described below.
 
       -b     Set  up  and  enable the Serial Port EMP parameters
              for Basic Mode management functions.  This does not
              set a username or password.
 
       -c     Configure and enable the Serial Port EMP parameters
              for Terminal Mode management functions, shared with
              BIOS Console Redirection.  This sets a new username
              and password.
 
       -d     Disable the serial port access for  IPMI  commands.
              The  serial  port  is  then only available for BIOS
              console and OS functions.  A  side-effect  of  this
              option is that it sets the default user (1) back to
              admin access.
 
       -n ser_chan
              Sets the IPMI channel number  for  the  EMP  serial
              port.  The default for this channel number is 1.
 
       -r     Read  Only.   This  option  just  reads  the Serial
              Parameter configuration without writing any values.
 
       -u username
              This specifies a username for the EMP Terminal Mode
              login.  It can be any string, up to 15  characters.
              If  -u is not used, the default user (null) will be
              assumed.  The username, if specified, will  be  set
              for user 3.
 
       -p password
              This specifies a password for the EMP Terminal Mode
              login.  It can be any string, up to 15  characters.
              A null password is used if none is specified.
 
       -l     Show LAN Parameters. This option reads and displays
              the LAN Parameter configuration also.
 
       -m0    Switch the Serial Port MUX to  Baseboard/BIOS  Con
              sole operation.  Set no other configuration parame
              ters.

       -m1    Switch the Serial Port MUX to Terminal Mode manage
              ment.  Set no other configuration parameters.
 
       -s     Set  up  and  enable the Serial Port EMP parameters
              for Shared operation between Basic Mode  management
              functions  and  Baseboard  (BIOS)  Remote  Console.
              This option switches the Serial Port MUX  to  Base
              board Console operation.
 
       -x     Causes extra debug messages to be displayed.
 
       -N nodename
              Nodename  of  the remote target system.  If a node
              name is specified,  IPMI  LAN  interface  is  used.
              Otherwise  the local system management interface is
              used.
 
       -R rmt_pswd
              Remote  password  for  the  nodename  given.    The
              default is a null password.
 
       -U rmt_user
              Remote   username  for  the  nodename  given.   The
              default is a null username.
 
EXAMPLES
       tmconfig -c
              Enables Terminal Mode management functions,  shared
              with BIOS Serial Console retirection.  The user can
              switch between serial console operations  and  IPMI
              Terminal  Mode  commands  by typing ESC ')' and ESC
              'Q'.
 
       tmconfig -s
              Enables Basic Mode management functions shared with
              BIOS  Serial  Console  redirection.   The  user can
              switch between serial console operations  and  IPMI
              Basic  Mode  management programs on the same serial
              port.
 
       tmconfig -d
              Disables  the  serial  port  management  functions.
              This  would be if only the BIOS Serial Console were
              used.

       How to login to a Terminal Mode console:
       ESC (                   (switch to Terminal mode)
       [SYS PWD -N ]           (login for default user, null psw)
       [SYS PWD -U ROOT -N PASSWORD]  (syntax example for user 3)
       [SYS 000157 ACTIVATE]   (activate advanced commands)
       [SYS HEALTH QUERY]
       [SYS HELP]
       [SYS PWD]               (logoff)
       ESC Q                   (switch to BIOS console)
       See IPMI 1.5 Spec, Appendix E, and Intel TIGPR2U  TPS  for
       more information.
 
DEPENDENCIES
       The  tmconfig  utility  is  intended  to configure the EMP
       serial port  on  the  server  for  shared  access  between
       BMC/IPMI  functions  and  BIOS  Console Redirection.  Some
       platforms only support only Basic Mode for BMC/IPMI  func
       tions.  Basic Mode requires a remote client application to
       utilize it (Windows ISC Console/DPC, or a special modified
       Linux  telnet).   There are some platforms which implement
       Terminal Mode via IPMI v1.5 Appendix E to make remote man
       agement  with  character  commands available on the serial
       port without a special remote client application.

       For example, Intel TSRLT2 systems would use "tmconfig  -s"
       for Basic Mode shared functions, but Intel TIGPR2U systems
       could use "tmconfig -c" to configure Terminal  Mode  func
       tions.  On your system, run "tmconfig -r" to check whether
       Serial Param(29): "Terminal Mode Config" is supported.  If
       not, configure Basic Mode via "tmconfig -s".
 
SEE ALSO
       pefconfig(8)
 
WARNINGS
       See  http://ipmiutil.sourceforge.net/  for the latest ver
       sion of tmconfig and any bug fix list.

PLATFORM SERIAL PORT CONFIGURATION EXAMPLES

  How to configure BIOS Console Redirection on the serial port.
  On Intel TIGPR2U:
    BIOS Setup (F2), Server, Console Redirection
    BIOS Redirection Port = serial 2
    ACPI Redirection = Disabled
    Baud Rate = 19.2K
    Flow Control = CTS/RTS
    Terminal Type = VT100+
  From Linux, run "tmconfig -c" for Terminal Mode shared configuration.

  On Intel TSRLT2, requires BMC >= 54:
    Serial Console Redirection = Enabled
    Serial Port = COM2 2F8 IRQ3
    Baud Rate = 19.2K
    Flow Control = CTS/RTS
  From Linux, run "tmconfig -s" for Basic Mode Shared configuration.
  
  For most other platforms, the serial console would be
  COM1 instead of COM2, but should be enabled in BIOS.

LINUX CONFIGURATION FOR SERIAL CONSOLE

  In /etc/lilo.conf, add
  append="console=tty console=ttyS1,19200n8"
  (and comment out the "message=" line because it includes graphics)
  Note that the append line can be placed in the global section
  and removed from each kernel section if there are no other differences.
  
  Or, edit /boot/grub/grub.conf as follows:
  # /boot/grub/menu1.list
  #gfxmenu (hd0,0)/message  # do not show the graphic interface
  default 0
  timeout 8
  #Using COM2
  serial --unit=1 --speed=19200 --word=8 --parity=no --stop=1
  # terminal --timeout=10 serial  (if serial only, no VGA)
  terminal --timeout=10 serial console
  title linux
      # Using COM2
      kernel (hd0,0) /vmlinuz  root=/dev/sda2  console=ttyS1,19200n8
      initrd (hd0,0) /initrd

  If MontaVista CGE 3.0, no change to /etc/inittab.
  If RedHat 9.0, RedHat AS 2.1, or MontaVista CGE 2.1, add to /etc/inittab:
  co:2345:respawn:/sbin/agetty ttyS1 19200 vt100
  If RedHat 7.x/8.0, add to /etc/inittab:
  co:2345:respawn:/sbin/mgetty -r -s 19200 ttyS1


3.6 FRUCONFIG(8)                                         FRUCONFIG(8)
 
NAME
       fruconfig - show Field Replacable Unit configuration data
 
SYNOPSIS
       fruconfig [-ax -N node -R pswd]
 
DESCRIPTION
       fruconfig is a program that uses IPMI commands to show FRU
       configuration data  and  optionally  write  an  asset  tag
       string  into  the  FRU  data.   Setting the asset tag is a
       function that can be used to uniquely identify  the  unit,
       even  if the storage devices are removed or changed.  This
       utility can use either the  /dev/ipmi0  driver  from  Mon
       taVista,  the /dev/imb driver from Intel, the /dev/ipmikcs
       driver from valinux, or the GNU FreeIPMI library.
 
OPTIONS
       Command line options are described below. 

       -a     This option specifies an asset  tag  string  to  be
              written  to the system FRU Product area.  The asset
              tag length is limited by the existing  FRU  Product
              data, but is usually allowed up to 16 characters.
 
       -x     Causes eXtra debug messages to be displayed.

       -N nodename
              Nodename  of  the remote target system.  If a node-
              name is specified,  IPMI  LAN  interface  is  used.
              Otherwise  the local system management interface is
              used.
 
       -R rmt_pswd
              Remote  password  for  the  nodename  given.    The
              default is a null password.
 
SEE ALSO
       showsel(8)
 
WARNINGS
       See  http://ipmiutil.sourceforge.net/  for the latest ver
       sion of fruconfig and any bug fix list.


3.7 ALARMS(8)                                               ALARMS(8)
 
NAME
       alarms - display and set alarm indicators
 
SYNOPSIS
       alarms [-r -i -c -m -n -p -o -x -N node -R pswd]
 
DESCRIPTION
       alarms is a program that uses IPMI commands to display and
       set alarm indicators, which are usually LEDs on the system
       chassis  front  panel.   This  utility  can use either the
       /dev/ipmi0 driver from  MontaVista,  the  /dev/imb  driver
       from  Intel,  the /dev/ipmikcs driver from valinux, or the
       GNU FreeIPMI library.
 
       Note  that  this utility may not be the only logic setting
       alarm states.  The BMC firmware, system  management  soft
       ware,  or cluster fault manager may also want to set alarm
       states.  Intel provides a Telco Alarms Manager  API  which
       presents a consolidated interface for all alarm management
       applications.

OPTIONS
       Command line options are described below.
 
       -r     Read-only.  Show the alarms status, but do not  set
              any  states.   This  is also the default mode if no
              parameters are specified.
 
       -iN    Sets the Chassis Identify feature, which can be  an
              LED  or  some  other  alarm.   If N=0, turn off the
              Chassis ID, otherwise turn the ID on for N seconds.
              Note that this function may not be supported on all
              systems, and specifying it will display an error if
              unsupported.
 
       -cN    Sets  the Critical Alarm.  If N=0, turn it off.  If
              N=1, turn it on.
 
       -mN    Sets the Major Alarm.  If N=0,  turn  it  off.   If
              N=1, turn it on.
 
       -nN    Sets  the  Minor  Alarm.   If N=0, turn it off.  If
              N=1, turn it on.
 
       -pN    Sets the Power Alarm.  If N=0,  turn  it  off.   If
              N=1, turn it on.

       -o     Sets all alarms off, including the Chassis ID.

       -N nodename
              Nodename  of  the remote target system.  If a node-
              name is specified,  IPMI  LAN  interface  is  used.
              Otherwise  the local system management interface is
              used.
 
       -R rmt_pswd
              Remote  password  for  the  nodename  given.    The
              default is a null password.
 
       -x     Causes extra debug messages to be displayed.
 
SEE ALSO
       showsel(8)
 
WARNINGS
       See  http://ipmiutil.sourceforge.net/  for the latest ver
       sion of alarms and any bug fix list.


3.8 WDT(8)                                                     WDT(8)
 
NAME
       wdt - display and set WatchDog Timer parameters
 
SYNOPSIS
       wdt [-d -e -r -t -x -N node -R pswd]
 
DESCRIPTION
       wdt  is  a  program that uses IPMI commands to display and
       set WatchDog  Timer  parameters.   This  utility  can  use
       either the /dev/ipmi0 driver from MontaVista, the /dev/imb
       driver from Intel, or the /dev/ipmikcs  driver  from  val
       inux.
 
       Note  that the device-independent way to manipulate watch
       dog timers in Linux is to use the /dev/watchdog interface.
       This  utility  is  an  example  of  how to access the IPMI
       watchdog parameters directly.
 
OPTIONS
       Command line options are described below.

       -d     Disables the watchdog timer.
 
       -e     Enables the watchdog timer.  The timer is not actu
              ally  started,  however,  until the timer is reset.
              The pre-timeout action is not enabled.
 
       -r     Resets the watchdog timer.   This  should  be  done
              every  N seconds if the timer is running to prevent
              the watchdog action (usually a system  reset)  from
              occurring.
 
       -tN    Set the watchdog Timeout to N seconds.  The default
              is 120 seconds (2 minutes).
 
       -x     Causes extra debug messages to be displayed.

       -N nodename
              Nodename of the remote target system.  If  a  node-
              name  is  specified,  IPMI  LAN  interface is used.
              Otherwise the local system management interface  is
              used.
 
       -R rmt_pswd
              Remote   password  for  the  nodename  given.   The
              default is a null password.
 
SEE ALSO
       showsel(8)
 
WARNINGS
       See http://ipmiutil.sourceforge.net/ for the  latest  ver
       sion of wdt and any bug fix list.


3.9 ICMD(8)                                                   ICMD(8)
 
NAME
       icmd  - a tool to send specific IPMI commands via the com-
       mand line.
 
SYNOPSIS
       icmd [-x -N node -R pswd] bus rsSa netFn/lun cmd [data bytes]
 
DESCRIPTION
       icmd  This  tool  sends  specific  IPMI  commands  to  the
       firmware.   The commands are composed as hex values on the
       command line.  This tool was written to allow in-band  use
       to match the DOS IPMITOOL.EXE program which is distributed
       with many Intel servers.  Certain scripts  or  pre-written
       commands  may have been supplied for the DOS tool that can
       now be used while the system is running Linux or  Windows.
 
       This  utility  can  use  either the /dev/ipmi0 driver from
       MontaVista,   the   /dev/imb   driver   from   Intel,  the
       /dev/ipmikcs driver from  valinux,  or  the  GNU  FreeIPMI
       library.

       This tool should only be used if you are familiar with the
       IPMI 1.5 specification, or you have  specific  pre-written
       commands to send.
 
OPTIONS
       Command line options are described below.
 
       -x     Causes extra debug messages to be displayed.

       -N nodename
              Nodename of the remote target system.  If  a  node-
              name  is  specified,  IPMI  LAN  interface is used.
              Otherwise the local system management interface  is
              used.
 
       -R rmt_pswd
              Remote   password  for  the  nodename  given.   The
              default is a null password.
 
PARAMETERS
       The following parameters are used by icmd.  Each is repre-
       sented as a two-digit hex byte.  The  parameters  have  no
       default values.
 
       bus    This byte contains the bus number for this command,
              usually 00.
 
       rsSa   This  is  the  resource slave address, usually 0x20
              for the BMC.
 
       netFn/lun
              This byte combines the net Function and Lun.  The 2
              low-order  bits  are  the  Lun and the 6 high-order
              bits are the net Function.  This representation  is
              consistent with the DOS IPMITOOL.EXE.

       cmd    This byte contains the IPMI command.
 
       [data bytes]
              This is a sequence of zero to 16 bytes that  repre-
              sent data bytes specific to this command.
 
EXAMPLES
       icmd 00 20 18 01 
       Sends the GetDevice ID command to the BMC.
 
       icmd 00 20 28 43 00 00 ff ff 00 ff
       Sends  a  Get  SEL entry command for the last entry in the
       firmware log.
 
SEE ALSO
       showsel(8)

WARNINGS
       See http://ipmiutil.sourceforge.net/ for the  latest  ver-
       sion of icmd and any bug fix list.


--------------------------
4.0  USE CASES
--------------------------

4.1 Usage of IPMI utilities for sensor thresholds
Get and set the Baseboard Temperature sensor threshold with 
the 'sensor' utility like this:
# sensor -t
[...]
000e SDR Full 01 39 20 sensnum 30 Baseboard Temp   = 21 OK   33.00 degrees C
        hi-crit 65.00 hi-noncr 60.00 lo-crit  5.00 lo-noncr 10.00
[...]
Using sensnum 30 and the hex raw reading (21) as a baseline from above.
# sensor -t -n 0x30 -l 0x0a
[...]
GetThreshold[30]: 30 1b 0a 05 00 3c 41 00
SetThreshold[30]: 30 03 0c 0b 0a 00 00 00
SetSensorThreshold[30] to lo=0a hi=ff, ret = 0
# 
This sets the lower non-crit to 12 C, and lower crit to 11 C.


4.2 Usage of IPMI utilities for BMC LAN configuration

Suppose there are a number of IPMI servers that need to have their
BMC LAN interface configured.  Shell access to the servers 
(via ssh or similar) is assumed.  

BMC LAN, Simple case, password is not changed:
[ssh connection]
# pefconfig
[ssh exit]

BMC LAN, Complex case, assuming that a password needs to be set and
that the session text (or script) must encrypt the password.  
So, using the gnupg.org utilities with public/private keys 
would look something like this:
[ Set up list (or db) of encrypted passwords & key by nodename.
  Note that the list and keyfile could reside locally, building
  the ssh script syntax, so that only the encrypted password is 
  exposed remotely. ]
[ssh connection]
# gpg --import mykey.file
# mynode=`uname -n`
# my_enc_psw=`grep $mynode mylist.file |cut -f2`
# pefconfig -P `gpg --decrypt $my_enc_psw`
[ssh exit]


4.3 Usage of IPMI Utilities to set watchdog timer

# wdt -e -t 180
wdt ver 1.8
-- BMC version 0.66, IPMI version 1.5
wdt data: 01 00 1e 00 10 e0 10 e0 
Watchdog timer is stopped for use with BIOS FRB2. Logging
               pretimeout is 30 seconds, pre-action is None
               timeout is 5736 seconds, counter is 5736 seconds
               action is No action
Setting watchdog timer to 180 seconds ...
wdt data: 04 01 00 00 08 07 08 07
Watchdog timer is stopped for use with SMS/OS. Logging
               pretimeout is 0 seconds, pre-action is None
               timeout is 180 seconds, counter is 180 seconds
               action is Hard Reset
#
Now add "wdt -r" to the crontab every 60 seconds (every 1 minute):
echo "* * * * * /usr/sbin/wdt -r" >>my.cron
crontab my.cron


4.4 Usage of kernel panic handler code (now CONFIG_IPMI_PANIC_EVENT):

If a Linux panic occurs, the bmc_panic module will automatically save 
the date/time of the panic, and minimal information about the panic.
This information will also be sent via SNMP to the remote management console,
and the Alarms panel LED will be turned on.  
If lkcd is also configured, a full crash-dump of the panic will be saved
for later analysis.
After this, the system will automatically reboot.
This provides instant notification to the administrator, and significantly
improved post-mortem diagnosis.

Without these features, the administrator may never have any indication that
the system had crashed, and no way to know how to diagnose and fix the problem.

To enable this, set CONFIG_IPMI_PANIC_EVENT=y and CONFIG_IPMI_PANIC_STRING=y
in the kernel .config file.  

You can also run pefconfig to enable sending an SNMP trap for a kernel 
panic as an "OS Critical Stop" event.

Make sure that the panic timeout is not zero (infinite), by using 
echo "5" > /proc/sys/kernel/panic
or by adding 'append="panic=5"' to the lilo or grub configuration.

After a panic occurs, you can then use showsel to view the firmware SEL 
for that event.  It should look something like this:
# showsel
[...]
2d04 07/21/04 07:54:22 SMI  20 OS Critical Stop 46 (Fat) 6f [a1 61 74]
2d18 OEM Event 20 00 Fatal excep
2d2c OEM Event 20 01 tion
[...]


4.5 Interpreting BMC LAN SNMP Traps from Platform Events.

There are MIB files provided for BMC LAN SNMP traps with this project.
They are installed into /usr/share/ipmiutil/bmclan*.mib, and sym-linked 
into /usr/share/snmp/mibs/.
The Platform Event Traps (enterprises.3183) are defined in bmclanpet.mib.
The Alert-on-LAN traps (enterprises.3183) are defined in bmclanaol.mib.

Note that Plaform Event Traps also have a 46-byte binary variable bindings 
field included with the trap.  
See Section 12.5 and 12.6 from the Intel ISM 5.x TPS for background.

Actual PET Trap Data from a System Restart Event trap: 

snmputil: trap generic=6 specific=1208065
  from -> 10.243.42.197
Variable = .iso.org.dod.internet.private.enterprises.3183.1.1.1
Value    = String <0xa4><0x12><0x00><0x5f><0x62><0xa1><0xd5><0x11><0x00><0x80><0x60><0xff><0x94><0x47><0x03><0x00><0x21><0x19><0x0c><0x7f><0x3b><0x12><0xff><0xff><0x20><0x20><0x00><0x01><0x83><0x00><0x00><0x01><0xff><0xff><0x00><0x00><0x00><0x00><0x00><0x19><0x00><0x00>
<0x01><0x57><0x00><0x0c><0xc1>

Byte Mapping 
Bytes of the trap variable binding data are mapped.  
An extra byte of data is at the end (47).

Byte Data    Meaning
1   0xa4    System GUID (16 bytes)
2   0x12    
3   0x00    
4   0x5f    
5   0x62    
6   0xa1    
7   0xd5    
8   0x11    
9   0x00    
10  0x80    
11  0x60    
12  0xff    
13  0x94    
14  0x47    
15  0x03    
16  0x00    
17  0x21    Sequence Number/Cookie (2 bytes)
18  0x19    
19  0x0c    Local Timestamp (4 bytes)
20  0x7f    
21  0x3b    
22  0x12    
23  0xff    UTC Offset (2 bytes)
24  0xff    
25  0x20    Trap Source Type
26  0x20    Event Source Type
27  0x00    Event Severity
28  0x01    Sensor Device
29  0x83    Sensor Number
30  0x00    Entity
31  0x00    Entity Instance
32  0x01    Event Data (8 bytes max, 3 bytes used)
33  0xff    
34  0xff    
35  0x00    
36  0x00    
37  0x00    
38  0x00    
39  0x00    
40  0x19    filler byte
41  0x00    Manufacturer ID (4 bytes, 000157=Intel)
42  0x00    
43  0x01    
44  0x57    
45  0x00    Product ID   (2 bytes)
46  0x0c
47  0xc1    extra byte

-------------------------------
5.0  IPMI UTILITIES ON WINDOWS 
-------------------------------
Files contained in the ipmiutil win32 zip file:
 alarms.exe
 fruconfig.exe
 hwreset.exe
 icmd.exe
 pefconfig.exe
 sensor.exe
 showsel.exe
 showselmsg.dll
 tmconfig.exe
 wdt.exe

The showselmsg.dll needs to be copied into the %PATH%, usually
%SystemRoot%\system32.  The other utilities can be run independently,
or added into the %PATH%.

The usage of the utilties is the same as in the ipmiutil 
UserGuide, with two caveats:
1) The remote (BMC LAN) options, -N/-R/-U, are not supported on Windows.
2) The only IPMI driver supported is the Intel IMB driver (imbdrv.sys), 
   which can be obtained from the Intel Resource CD for your system, 
   from the ISM CD, or from support.intel.com.

How to install the Windows IPMI driver (from Resource CD)
cd c:\temp
copy d:\ism\software\win32\pi\common\imb*.*
copy d:\ism\software\win32\pi\common\win2k*.exe
ren imbdrv2k.sys imbdrv.sys
copy imbapi.dll %SystemRoot%\system32
win2kinstall c:\temp\imbdrv.inf *IMBDRV
driverquery   (shows the drivers currently installed/running)

To build the ipmiutil EXEs for Windows from source,
the WIN32 compile flag needs to be turned on.
The ipmiutil doc/mk.bat shows a how to compile and link 
the util/*.c files, although many people prefer to do 
makes with Microsoft VisualStudio.  
The build environment assumes that VisualStudio/VC98 and 
Windows 2003 DDK are installed.

To build the showselmsg.dll from doc/showsel.mc:
set TARG=showsel
mc -U %TARG%.mc
rc -r %TARG%.rc
link /MACHINE:IX86 -dll -noentry -out:%TARG%msg.dll %TARG%.res

--------------------------
6.0  PROBLEMS
--------------------------
Note that each tool has an option for additional debug output (-x).

Contact maintainer for best-effort support:  arcress@users.sourceforge.net
or use the ipmiutil-developer mailing list:
       http://lists.sourceforge.net/lists/listinfo/ipmiutil-developers 

Return code = 0 means success, negative numbers indicate failure.
Completion Codes are defined in IPMI 1.5, Table 5-2, and are also included 
below:
Code  Description
----  -----------------------------------------
0x00, "Command completed successfully",
0xC0, "Node Busy",
0xC1, "Invalid Command",
0xC2, "Command invalid for given LUN",
0xC3, "Timeout while processing command",
0xC4, "Out of space",
0xC5, "Invalid Reservarion ID, or cancelled",
0xC6, "Request data truncated",
0xC7, "Request data length invalid",
0xC8, "Request data field length limit exceeded",
0xC9, "Parameter out of range",
0xCA, "Cannot return requested number of data bytes",
0xCB, "Requested sensor, data, or record not present",
0xCC, "Invalid data field in request",
0xCD, "Command illegal for this sensor/record type",
0xCE, "Command response could not be provided",
0xCF, "Cannot execute duplicated request",
0xD0, "SDR Repository in update mode, no response",
0xD1, "Device in firmware update mode, no response",
0xD2, "BMC initialization in progress, no response",
0xD3, "Destination unavailable",
0xD4, "Cannot execute command. Insufficient privilege level",
0xD5, "Cannot execute command. Request parameters not supported",
0xFF, "Unspecified error"

--------------------------
7.0  RELATED INFORMATION
--------------------------
Links with information related to the IPMI Management Utilities project.

ipmiutil project on sourceforge     http://ipmiutil.sourceforge.net
panicsel project on sourceforge     http://panicsel.sourceforge.net
Carrier Grade Linux Working Group   http://www.osdl.org/projects/cgl/
Carrier Grade Linux Edition         http://developer.osdl.org
Intel Carrier Linux Technology      http://carrierlinux.org/
IPMI Specification           http://www.intel.com/design/servers/ipmi/index.htm

OpenIPMI project                    http://sourceforge.net/projects/openipmi/
  by Corey Minyard of MontaVista       (home=http://openipmi.sourceforge.net)
Intel imb ipmidrvr                  http://downloadfinder.intel.com/scripts-df/Product_Search.asp?Prod_nm=ipmi*driver*source
valinux IPMI driver                 http://cvs.sf.net/cgi-bin/viewcvs.cgi/ipmitools/ipmitools/kernel/kcs/patches/2.4.x/ 
Intel/Radisys combined IPMI driver  http://cvs.developer.osdl.org/viewcvs/viewcvs.cgi/kernel/linux-2.4.18/patches/ipmi_comb/
BMC WatchDog Timer patch     http://cvs.developer.osdl.org/viewcvs/viewcvs.cgi/kernel/linux-2.4.18/patches/bmcwdt/ 

San Mehat's ipmitools project       http://sourceforge.net/projects/ipmitools/
FreeIPMI project                    http://sourceforge.net/projects/freeipmi/
IPMI-BSD project                    http://sourceforge.net/projects/ipmi-bsd/
PHP Poor-Man's Sys Mgt Software     http://sourceforge.net/projects/phppmsms/
lm-sensors project                  http://secure.netroedge.com/~lm78/

