ipmitool

                            Duncan Laurie

                ipmitool-devel@lists.sourceforge.net

Overview

========

ipmitool is a utility for managing and configuring devices that support

the Intelligent Platform Management Interface.  IPMI is an open standard

for monitoring, logging, recovery, inventory, and control of hardware

that is implemented independent of the main CPU, BIOS, and OS.  The

service processor (or Baseboard Management Controller, BMC) is the brain

behind platform management and its primary purpose is to handle the

autonomous sensor monitoring and event logging features.

The ipmitool program provides a simple command-line interface to this BMC.

It features the ability to read the sensor data repository (SDR) and print

sensor values, display the contents of the System Event Log (SEL), print

Field Replaceable Unit (FRU) inventory information, read and set LAN

configuration parameters, and perform remote chassis power control.

Background

==========

I originally wrote ipmitool while between projects and employeed at Sun

Microsystems.  Sun had just embarked on a new line of general-purpose x86

servers that included an OEM Intel board with an IPMIv1.5 BMC on board.

It started with an idea that remote chassis power control would be a handy

feature for my systems in the lab and from there it grew into a multi-

purpose tool that lots of people found useful.  I decided to release it

under a BSD license and give others the chance to make use of it.

ipmitool was not written to provide large-scale (aka Enterprise) management

application functionality.  The functionality that ipmitool proivides is

easily accomplished by sending simple IPMI request messages and parsing

the returned response.  It is intended to be used by system administrators

who like the simplicity and scriptability of command-line utilities, as

well as those debugging or developing their own BMC implementations.

Requirements

============

Obviously the largest requirement is hardware with a service processor

that supports the IPMI specification.  Many x86-based servers are now

comming with IPMI support, check with your preferred hardware vendor

about available prodcuts.

Once you are certain you have the required hardware, you then need to

decide how you want to access the BMC.  The most common case involve

access through the System Interface or over the LAN.  (or serial, but

currently ipmitool does not support the serial interface)

System Interface

----------------

There are multiple types of system interfaces, but they are all similar

enough to allow a single well-designed driver to support them all.  

Different types of system interfaces include Keyboard Controller Style

(KCS), Block Transfer (BT), System Management Interface Chip (SMIC) and

SMBus.  Different hardware vendors will have different preference and

implementations.

On Linux the OpenIPMI kernel driver should support all of these system

interfaces and it should be a simple matter of loading the right

kernel modules and setting up the device node to use it.  The driver

module names vary slightly in different kernel versions, but for all

releases you need these two modules:

  ipmi_msghandler: incoming and outgoing message handler

  ipmi_devintf: character device interface to IPMI driver

For 2.4.x and early 2.6.x kernels you need to choose a module based on

the type of system interface your hardware supports.  For example:

  ipmi_kcs_drv: Keyboard Controller Style driver

More recent 2.6.x kernels have combined these into a single module:

  ipmi_si: a universal IPMI system interface driver

See the documentation that comes with your distribution and/or kernel

for more information on what kernel modules are required.  Once the

required modules are loaded and the driver has found a suitable system

interface to the BMC then you need to ensure the device node at

/dev/ipmi0 is pointing at the correct major number.

This is because OpenIPMI is given a dynamically assigned major number

when it is loaded, but depending on what other modules are present

this number may be anywhere from 254 on down.  The easiest way to tell

is to check the output of /proc/devices and see what major number the

"ipmidev" device is assigned to.

There is a sample script included with ipmitool called ipmi.init that

can be used to automate this process at bootup.

LAN Interface

-------------

This is often referred to as "IPMI-over-LAN" and defines how IPMI messages

can be sent to and from the BMC encapsulated in Remote Management Control

Protocol (RMCP) packets which are then transferred as UDP datagrams.

IPMI-over-LAN is only supported with version 1.5 and higher of the IPMI

specification.  The RMCP packet format is defined by the Alert Standard

Forum, and it has been followed up with the RMCP+ protocol that adds

encryption and payload support.  The IPMIv2 specification was updated

accordingly to to support the RMCP+ protocol and brings with it enhanced

security with encryption as well as support for Serial over LAN.

There are different types of LAN interfaces as well.  Some systems have

shared management networks where the NIC will intercept UDP packets to

port 623 and redirect them to the BMC over SMBUS.  This type of LAN

interface requires that the BMC be configured with the same settings that

the system uses.  It also suffers from an increased security risk just by

the nature of sharing that interface with normal traffic.

I have also seen bugs in some implementations that have rendered the

IPMI-over-LAN feature "dangerous" to enable in some situations.  (in

particular there can be an issue with RPC because it will sometimes choose

to use port 623 and you will lose response packets...)

There is a sample shell script included with ipmitool called bmclanconf

that can be used to simplify the LAN settings configuration process using

the System Interface to configure the settings.  In some cases the

hardware will come with a utility (often a DOS bootable CD) for configuring

enabling the LAN interface as well.

In order to support the IPMIv2.0 interface you must have an OpenSSL library

with the required encrytion functions.  Recent distributions should have

no problems.  The IPMIv1.5 interface will attempt to use OpenSSL for MD5

hash function at compile time but if that is not found it will use an

internal library.

IPMB Dual Bridging in  IPMITOOL

-------------------------------

IPMI offers a standard messaging interface.

The following concepts are related to this messaging interface:

Channel type     : Communication channel type (SMS/KCS, IPMB, LAN) 

Channel number   : Channel descriptor

Requester        : Address of the requester

Responder        : Address of the responder

NetFN            : The logical function  for the request/response.

Command          : The command number 

Sequence         : An ID identifiying the request/response pair

Message tracking : The ability to match request/response pair.

When a communication is issued through any of the channels, an application 

formats a request and expect a response. 

Direct Command

--------------

The simplest form of communication is a "direct command" using SMS/KCS

Example:

 ipmitool raw 6 4

  55 00

This send raw command 4 (selftest) from netfn 6(application) to KCS, the driver 

takes care of 'message tracking' and provides the answer.

Hopefully, the application also includes a "human readable" instance of the API:

 ipmitool mc selftest

 Selftest: passed

Bridged Command

---------------

One slightly more complicated communication mode is the so-called 

"bridged command" using IPMB. 

Example:

 ipmitool -m 0x94 -t 0x9a raw 6 4

 55 00

 or

 ipmitool -m 0x94 -t 0x9a mc selftest

 Selftest: passed

This still sends the same command  4 (selftest) from netfn 6(application) to 

the target. However, to do so, the command is encapsulated (by the driver) and

sent using the command 0x34 (send message) from netfn 6(application) to KCS. 

Then KCS is polled by the driver until a message has been received, then the

driver uses command 0x33 (get message). The driver also tracks the message 

and makes sure the response matches the request. Then it decapsultates the

message and gives the response back to the application.

Dual Bridged Command

--------------------

Things get a little more ugly when the application needs to reach a management

controller sitting on an interface (or channel) not directly connected to the 

BMC/IPMC. In the case the application must encapsulate its message itself and 

request the IPMC to deal with message tracking itself.

Its been working well with IPMITOOL on the LAN interface with:

 ipmitool -H <ip> -U <user> -P <password> -B 0 -T 0x8a  -m 0x20 -t 0x7a -b 7  

    mc selftest

However, trying to dual bridge commands locally with :

 ipmitool -B 0 -T 0x9a -m 0x94 -t 0x7a -b 7 mc selftest didn't work 

 (it returned the same data as  ipmitool -m 0x20 -t 0x7a -b 7 mc selftest )

The reason was that the "openipmi" interface pluging didn't 

encapsulate/decapsulate the message and didn't even detect the intent

to double bridge the request.

 ./src/ipmitool -B 0 -T 0x8a -m 0x94 -t 0x7a -b 7 mc selftest

-B    0  : transit channel for first bridge level (channel 0: IPMB-0) 

-T 0x8a  : transit destination address (remote IPMC address)

-m 0x94  : source address (local IPMC address on IPMB-0)

-t 0x7a  : remote target (AMC IPMB-L address)

-b    7  : remote channel (channel 7: IPMB-L)

The transit source address (remote IPMC address on remote channel) is 

automatically assigned by the remote IPMC.

Payload Size Limit

------------------

Because some commands return a lot of data (fru read/get sdr) and because 2 

levels of encapsulation are used, some command will fail.

For instance this works.

ipmitool -H <ip> -U <user> -P <password>  -B 0 -T 0x8a  -m 0x94 -t 0x7a -b 7 

    mc selftest

but this does not:

ipmitool -H <ip> -U <user> -P <password>  -B 0 -T 0x8a  -m 0x94 -t 0x7a -b 7 

    fru print.

Usage

=====

All invocations of ipmitool require specifying an interface to use, unless

you want to use the default interface as set at compile time.  Each call

must also specify a command to run.  You can see the list of supported

interfaces and which is default as well as a list of top level commands in

the usage output available with the -h option:

usage: ipmitool [options...] <command>

   -h            This help

   -V            Show version information

   -v            Verbose (can use multiple times)

   -c            Display output in comma separated format

   -I intf       Interface to use

   -H hostname   Remote host name for LAN interface

   -p port       Remote RMCP port [default=623]

   -L level      Remote session privilege level [default=USER]

   -A authtype   Force use of authtype NONE, PASSWORD, MD2 or MD5

   -U username   Remote session username

   -P password   Remote session password

   -f file       Read remote session password from file

   -a            Prompt for remote password

   -E            Read password from IPMI_PASSWORD environment variable

   -m address    Set local IPMB address

   -t address    Bridge request to remote target address

Interfaces:

    open         Linux OpenIPMI Interface [default]

    imb          Intel IMB Interface

    lan          IPMI v1.5 LAN Interface

    lanplus      IPMI v2.0 RMCP+ LAN Interface

Commands:

    raw          Send a RAW IPMI request and print response

    lan          Configure LAN Channels

    chassis      Get chassis status and set power state

    event        Send pre-defined events to BMC

    bmc          Print BMC status and configure global enables

    sdr          Print Sensor Data Repository entries and readings

    sensor       Print detailed sensor information

    fru          Print built-in FRU and scan SDR for FRU locators

    sel          Print System Evelnt Log

    sol          Configure IPMIv2.0 Serial-over-LAN

    user         Configure BMC users

    channel      Configure BMC channels

    session      Print session information

    shell        Launch interactive IPMI shell

    exec         Run list of commands from file

    set          Set runtime variable for shell and exec

Commands

========

More help on the supported commands can be found by running them with the

help argument, for example "chassis help".  There are a few commands with

special meaning:

> shell:  This command will launch an shell interface to the ipmitool

  command set.  You can use this for interactively entering commands to

  monitor system status.  An example session:

# ipmitool -I open shell

ipmitool> chassis status

System Power         : off

Power Overload       : false

Power Interlock      : inactive

Main Power Fault     : false

Power Control Fault  : false

Power Restore Policy : always-off

Last Power Event     : command

Chassis Intrusion    : active

Front-Panel Lockout  : inactive

Drive Fault          : false

Cooling/Fan Fault    : false

ipmitool> user list 7

ID  Name             Callin  Link Auth  IPMI Msg   Channel Priv Limit

1                    true    false      true       ADMINISTRATOR

ipmitool> exit

> exec:  This command will read a text file and execute ipmitool commands

  in sequence.  It can be used for scriptable commands:

# cat lansetup.scr

lan set 7 ipsrc static

lan set 7 ipaddr 10.1.1.10

lan set 7 netmask 255.255.255.0

lan set 7 defgw ipaddr 10.1.1.254

# ipmitool -I open exec lansetup.scr

Setting LAN IP Address to 10.1.1.10

Setting Lan Subnet Mask to 255.255.255.0

Setting Lan Default Gateway IP to 10.1.1.254

> set:  This command can be used by the shell and exec modes to configure

  various session parameters:

  hostname <host>        Session hostname

  username <user>        Session username

  password <pass>        Session password

  privlvl <level>        Session privilege level force

  authtype <type>        Authentication type force

  localaddr <addr>       Local IPMB address

  targetaddr <addr>      Remote target IPMB address

  port <port>            Remote RMCP port

  csv [level]            enable output in comma separated format

  verbose [level]        Verbose level

# cat getstatus.scr

set hostname sf-v20z-1

set password admin

chassis status

# ipmitool -I lan exec getstatus.scr

Set session hostname to lx50

Set session password

System Power         : off

Power Overload       : false

Power Interlock      : inactive

Main Power Fault     : false

Power Control Fault  : false

Power Restore Policy : always-off

Last Power Event     : command

Chassis Intrusion    : active

Front-Panel Lockout  : inactive

Drive Fault          : false

Cooling/Fan Fault    : false

ipmievd

=======

Included with ipmitool is another utility called ipmievd that is a daemon

which will listen for events from the BMC that are being sent to the SEL

and also log those messages to syslog.  By default when run (as root) with

no arguments it will daemonize and poll on the OpenIPMI device waiting for

an event notification.  Upon receipt of an event it will log it to syslog

with the LOG_LOCAL4 facility.  You can test ipmievd by sending test events

over the LAN interface with ipmitool:

remote# ipmievd

local$ ipmitool -I lan -H lx50 -P admin event help

usage: event <num>

   1 : Temperature - Upper Critical - Going High

   2 : Voltage Threshold - Lower Critical - Going Low

   3 : Memory - Correctable ECC

local$ ipmitool -I lan -H lx50 -P admin event 1

Sending Temperature - Upper Critical - Going High event to BMC

local$ ipmitool -I lan -H lx50 -P admin event 2

Sending Voltage Threshold - Lower Critical - Going Low event to BMC

local$ ipmitool -I lan -H lx50 -P admin event 3

Sending Memory - Correctable ECC event to BMC

remote# tail /var/log/messages   (timestamps removed)

ipmievd: Waiting for events...

ipmievd: Temperature Sensor 30 - Upper Critical - going high

ipmievd: Voltage Sensor 60 - Lower Critical - going low

ipmievd: Memory Sensor 01 - Correctable ECC

Resources

=========

IPMItool homepage

http://ipmitool.sourceforge.net

IPMItool manpage

http://ipmitool.sourceforge.net/manpage.html

IPMItool overview paper from Linux.conf.au 2004

http://ipmitool.sourceforge.net/lca2004_ipmitool.pdf

Intelligent Platform Management Interface specification

http://www.intel.com/design/servers/ipmi/spec.htm

OpenIPMI project: Linux IPMI kernel driver and userland library

http://openipmi.sourceforge.net

IPMItool commit archive

https://lists.sourceforge.net/lists/listinfo/ipmitool-cvs