1) Questions about the driver
1.1) I'm trying to do a send message command, but it fails. Why
can't I do this?
You know too much about IPMI :-). OpenIPMI does all this work
for you. To send a message out on IPMB, you set up an IPMB
address and send the message to that address (without all that
nasty send message stuff). It's much easier. Try it, you'll
1.2) I *really* want to do a send message command. How do I do it?
Sorry, you can't. It's not that I have it out for you, it has to
do with the technical details of IPMI. If you have multiple
users of an IPMI system, you have to have a central mechanism to
manage information. You have sequence numbers that have to be
assigned and managed; if the same applications used the same
sequence numbers then chaos would ensue. Since the OpenIPMI
driver allows multiple users (and has users both inside and
outside the kernel) it can't allow users to directly do send
2) Questions about the library.
2.1) Why is ipmi_ui so ugly?
Well, ipmi_ui is a test program that I wrote for my own purposes.
I'll try to clean it up in the future and make it into something
useful, and it's certainly ugly, but it's primarily for my
In general, it has been replace with the ipmish command, which
provides a much more consistent interface to the system. It is
much more consistent and is well documented. It is perhaps not
quite as nice for interactive use.
2.2) What if I just want to send some IPMI commands.
Then "ipmicmd" is the tools for you. It can connect to a system
interface or to a LAN connection and let you directly enter
2.3) I'm trying to write a little program that comes up and queries a
few things. Can I use the OpenIPMI library to do that?
Yes, you can. In the ipmi_open_domain() command, you can turn on
and off the things you want, so you can trim down the startup
process to speed it up.
2.4) Why can't I just perform an operation and immediately get the
results? Why all these callbacks?
Read the documenation for details. The OpenHPI interface
(http://openhpi.sourceforce.net) is expected to sit on top of the
OpenIPMI library and provide an interface more like that. Plus,
you can write your own wrappers to do it. It's not possible to
write event-driven wrappers on top of a non-event-driven
2.5) Can I have multiple OpenIPMI session from different programs to
the same interface?
Certainly. I do it all the time :-)
The main problem is the System Event Log (SEL). Somebody has to
delete items from the SEL. You have a couple of options...
If you don't care about the SEL, then set the SEL rescan time to
zero with ipmi_domain_set_sel_rescan_time() or disable it with
the startup options. This will turn off the SEL completely.
If you do care about SELs on multiple programs, you will have to
develop a protocol between all the users. You have to have a way
to let all the listeners get all the SELs, but still delete items
from the SEL in a timely manner. I recommend that you set the
SEL rescan time to a value, and for every event receive wait
double that value before deleting it. OpenIPMI will correctly
handle multiple things deleting items from the SEL.
2.6) Can you open more than one IPMI session from OpenIPMI?
Certainly. You can create as many connections and domains as you
like, the library has no limitiation.
2.7) I have an xyz computer, does OpenIPMI support it?
That depends on a lot of things. Does the box have IPMI? Most
systems do not, it's currently mostly on high-end system. If the
system does have IPMI, OpenIPMI will probably support it. It may
not support the full function of your system though. Output
devices are not defined by the IPMI spec, so they are all OEM and
require custom code to control them. Sensors that do not appear
in an SDR repository will not be supported without custom code.
Any things custom to the system will probably not be supported.
2.8) What interfaces does OpenIPMI support?
OpenIPMI currently supports system interfaces through the
OpenIPMI device driver and LAN interfaces. It does not support
serial interfaces or any type of callback devices.
2.9) Does OpenIPMI support ICMB?
Not currently, although it shouldn't be hard to add.
2.10) How do I learn more about IPMI?
Not much information currently exists. The OpenIPMI web site has
a pointer to the specs and the documentation that comes with
IPMI, but the spec is very hard to read and the documentation is
really more marketing level. The documentation that comes with
OpenIPMI provides a more gentle introduction to IPMI (you should
certainly read it before you read the spec) but it's more focused
on OpenIPMI, not IPMI proper.
Someone needs to write a book (and it's not going to be me).
2.11) What does OpenIPMI do?
OpenIPMI attempts to handle a lot of the difficult parts of IPMI
for the user; as much as it can without making too many policy
decisions for the user. For instance, it:
* Fetches all the SDRs and translates them into sensors and
* Manages access to the SEL.
* Handles the interface, which is especially hard for LAN
* Handles fetching FRU information for entities.
* Lets you deal directly with sensors and entities.
* Periodically scans all the information it manages to see if
it has changed.
* Decodes incoming events, correlates them with sensors,
translates raw values into useful values, and delivers them
with the sensor object.
* Allows OEM code to plug in to fix up things and present
non-standard devices through standard interfaces.
Basically, the user just has to start up the connection and wait
for things to happen. As OpenIPMI finds things, it will report
them and the user can take action. It is designed to remove the
low-level details from the user's concern and only present the
things the user is really interested in handling.
2.12) I don't like the way OpenIPMI does x.
You may disagree with implementation decisions I have made and
that's fine. You can make suggestions, submit patches, and work
with me on this. Or you may write your own IPMI library. Or you
may pillage OpenIPMI to get what you want. Like Linus holds
final say on what goes into his distribution of Linux, I hold
final say on what goes into my distribution of OpenIPMI. But
that doesn't mean you can't do your own work on it.
2.13) Why did you write OpenIPMI?
OpenIPMI was originally written to support a customer who needed
an interface for their IPMI platform. It was also designed with
HPI in mind, for something to implement as the base to an HPI
2.14) I just want to use pieces of OpenIPMI, can I?
Well, it's open source. But unfortunately, OpenIPMI is not
terribly modular as a whole. Certain parts (the interface code,
for instance) can be used stand-alone. But SDRs, MC, SELs,
domains, sensors, etc. all know about each other. It's somewhat
inescapable, really, the concepts are intertwined. It would be
fairly easy to take any individual piece of the code (the sdr.c
code, for instance) and change it to work in a different system,
but you would have to change the code to do that.
2.15) Why is the OpenIPMI interface the way it is (bad, good, ugly,
elegent, simple, obtuse, etc)?
My basic philosophy of API design is:
1) Users should only have to deal with the objects they really
care about. You should distill the interface down to what the
user really cares about. Think about it from the user's point
of view and implement what they want.
2) Users (especially me) have a hard time dealing with large
numbers of types. Distill the types down to the essentials.
Don't overload types with information that doesn't belong in
them, either. Essentials are essentials; don't go beyond
3) Interfaces should be designed with extensibility in mind. All
types should be opaque pointers so that the internal
representation and implementation can change without the
binary or logical interface changing. If you make an
exception on this, it better be for a really good reason.
4) Use the basic types of the language as much as possible. It's
better to have more functions than types.
I'm very picky about this. I have seen too many bad APIs; ones
based on the implementation, not the needs of the user.
2.16) My IPMI system has some broken information in it. Can I fix it
Sure. You can write OEM code that ties in to when objects are
added to the system and fix them up as necessary. The details
of this are beyond the scope of the FAQ, but you can look in
lib/oem_*.c for examples.
2.17) It takes a long time to find all the information about a system
on IPMB. What's the deal?
Unfortunately, the base library can't really know what exists or
where it should exist, so it has to scan everything on the bus.
You can write an OEM plugin or scan the addresses you are
interested in by hand.
If you don't care about the information, as of version 1.4.4 you
can skip those steps via options to the ipmi_open_domain()
function or the startup parms to ipmish or the Perl interface.
2.18) I want to know when OpenIPMI is done finding everything in the
Unfortunately, there is no concept of "done" in IPMI. IPMI
allows a dynamic environment with elements of the system coming
and going. You need to re-think your philosophy here and design
software that can dynamically manage elements of the system
coming and going. OpenIPMI will tell you when it finds things,
and then you can manage them.
But bowing to popular demand, though, the 1.4 version of OpenIPMI
adds a "done" callback to the ipmi_open_domain function that lets
you know when OpenIPMI has finished the first pass of everything
(SDRs, SELs, FRUs, IPMB scan). There is no guarantee that it
found everything in the first pass, and you should handle
dynamically adding things later.
2.19) How do I build the Perl interface?
The Perl interface uses swig 1.3.22 or later, which is available
from http://www.swig.org. That must be installed and in your
path to build the Perl interface. You must also have the
development libraries for Perl installed, of course.
2.20) How do I catch SNMP traps with OpenIPMI?
Although OpenIPMI has infrastructure to handle traps, it does not
catch them for you. You have to provide the software to catch
the traps and then you can tell OpenIPMI about them. The
ui/basic_ui.c code has some example SNMP trap code using the
netsmp and ucsdsnmp libraries.
2.21) Why does it take a long time to get events from OpenIPMI?
The standard interface to the event log is polled, and the polling
time is 5 seconds by default. You can change the polling time if
you don't care about the additional load.
A system interface (SMI) does have an immediate event receive
capability; when an event comes in it goes into the system log and
into a queue. OpenIPMI does nt enable tis by default, you must
enable it yourself with a "Set BMC Global Enables Command".
LAN interfaces may be capable of sending SNMP traps when an event
comes in. This is through the Platform Event Traps and is fairly
complicated. OpenIPMI provides a way to configure this more
easily, but you still have to know what you are doing. See
question 2.20 for how to handle these traps.
2.22) What crypto does OpenIPMI implement/use?
OpenIPMI implements MD2 and MD5. It's questionable whether those
are crypto algorithms or not, but I'm including them just to be
For the IPMI 2.0 RMCP+ algorithms, OpenIPMI requires the OpenSSL
package. OpenIPMI will work without OpenSSL, but then it will not
be able to use the advanced encryption algorithms. The algorithms
used by OpenIPMI are: HMAC-SHA1 (96 bit) and HMAC-MD5 (128 bit) for
authentication and integrity. AES-CBC (128 bit) is the only option
for encryption. In the future, RC4 (40 bit and 128 bit) may be
implemented per the spec.
The OpenIPMI authentication/encryption framework is pluggable and
users could write their own algorithms if they wish.
2.23) How do I interpret the OpenIPMI numeric error values?
Nothing should really be printing these values except for logs and
tracing. However, a lot of these come out from sample
applications. However, I'll go over a little to make tracing and the
The top 8 bits of an error are the error type (basically where the
error came from). The rest of the value is the error itself; make
sure to use the proper IPMI_xxx_ERR_VAL() to extract it. The
error types are:
* 00 - An OS error or an error from OpenIPMI itself. These are
standard errno values and can be decoded with strerror()
* 01 - An error from the remote management controller (An IPMI error).
You can look these up in the IPMI manual.
* 02 - RMCP+ error. These are in the IPMI LAN section of the IPMI
* 03 - SoL (Serial Over LAN) errors. These are in the SoL section
of the IPMI manual.
You can convert any of these errors to a human-readable (currently
English only) string using ipmi_err_get_string(). See
include/OpenIPMI/ipmi_err.h for more details on these things.