This is the OpenIPMI library, a library that makes simplifies building complex IPMI management software.

IPMI is a specification detailing how to detect and manage sensors in a system. It also specifies some chassis-level thing like power control, reset, FRU (Field Replaceable Unit) information, and watchdogs.

However, IPMI has become much more than that. Vendors have added extensions to IPMI for doing many thing, including controlling LEDs, relays, character displays, and managing hot-swapping components. In general, it has become the "standard" way to handle hardware maintenance in a system.

IPMI specifies a set of interconnected intelligent Management Controllers (MCs). Each MC is a small CPU that manages a set of sensors and/or output devices. The "main" MC is called the Baseboard Management Controller (BMC); it provides the external interfaces into the system.

Each MC may have a set of Sensor Data Records (SDRs). An SDR details information about a sensor. Some SDR records also have information about entities, such as their name, the FRU information, and what other entities they are contained in.

Entities are the physical objects in the system (boards, CPUs, fans, power supplies, etc.) A sensor is attached to the entity it monitors; the SDR record tell what entity a sensor monitors.

IPMI specifies several external interfaces to the BMC. One set is local interfaces directly to a CPU, a local CPU connections is called a system interface. The other is external interfaces through a LAN, serial port, or modem. The external interfaces allow a system to be managed even when it is turned off, since the BMC is always powered when the system is plugged in.

IPMI has a strong bent toward complete "chassis" systems, basically a box with one main board with CPUs; a BMC, and perhaps a few satellite MCs in things like power supplies. It is being rapidly adopted in "shelf" systems, which has a set of slots where you can plug in complete single-board computers. In shelf systems, the BMC becomes a central shelf manager that manages all the boards in the shelf. Although IPMI was not designed for this, it does a pretty good job of extending into this architecture.

Notice that in the description above, OpenIPMI was designed to aid building "complex IPMI management software". That's a carefully chosen description.

Most of the OpenIPMI library was designed for building complicated systems that continuously monitor IPMI hardware. It's not for little things that simply want to get some information, do something, and leave (unless that information is elaborate information).

OpenIPMI will connect with an IPMI controller, detect any management controllers on the bus, get their SDRs, manage all the entities in the system, manage the event log, and a host of other things. As you might imagine, that is a fairly lengthy process on a complex system.

OpenIPMI is also dynamic and event-driven. It will come up and start discovering things in the managed system. As it discovers things, it will report them to the software using it (assuming the software has asked for this reporting). This process of discovery is never done from OpenIPMI's point of view; things can come and go in the system and it will report these changes as it detects them. This can be a little confusing to people who want a static view of their system. OpenIPMI has no static view (though it does have a current view). When you make a connection, it will report when the connection is up; but the system will be "empty". You have to wait for OpenIPMI to report the things it finds.

It is possible to use OpenIPMI's low-level connection code if you want to do a direct connection to a BMC (through the LAN or system interface). You can see the code in sample/ipmicmd.c for an example of how to do this. Most of the other pieces of OpenIPMI are not useful by themselves, though, because they are intrinsically tied together.

OpenIPMI is built with standard autoconf/automake.

You must configure OpenIPMI before you compile it. To do this, change to the main OpenIPMI directory and execute "./configure". The configure script will detect what is available in the system and configure itself accordingly.

By default, the configure script will cause OpenIPMI to be installed in the "/usr/local" prefix. This means that the include files go into /usr/local/include/OpenIPMI, the libraries go into /usr/local/lib, the executables go into /usr/local/bin, etc. If you want to change the prefix, use the "--prefix=" option to configure. For instance, to install in /opt/OpenIPMI, you would do: ./configure --prefix=/opt/OpenIPMI

Note that OpenIPMI will attempt to detect and use either the NET SNMP or UCD SNMP libraries. Note that if your NET SNMP or UCD SNMP library is in a non-standard location, you will need to use the '--with-ucdsnmp=' option with configure to specify the actual path to your library. You also must have the development system for your SNMP library installed. If you don't have the development system installed, just the runtime libraries, OpenIPMI will not detect or use the SNMP libraries. If you do not want to use the SNMP libraries even if they are installed, you can specify '--with-ucdsnmp=no' as a configure option.

After you have configured OpenIPMI, type "make" to build it. To install it in the prefix you defined, do "make install".

OpenIPMI requires the following packages:

• popt
• curses, ncurses or termcap

OpenIPMI can use, but does not require, the following packages:

• netsnmp or ucdsnmp - netsnmp is the preferred SNMP package, but it will use either of these. Without this, the sample programs will not be able to receive SNMP traps, but there is no functional change to the library.
• openssl - This is required for IPMI 2.0 RMCP+ encryption and authentication support. See FAQ item 2.22 for details.
• glib (along with pkgconfig) - glib 2.0 is preferred, but glib 1.2 will be used if 2.0 is not available. This is simply an OS handler for glib and it not used for anything else in OpenIPMI itself, but is useful for users using glib. Note that OpenIPMI will be able to use both glib 1.2 an glib 2.0 at the same time, but this is difficult and not recommended.
• swig 1.3.21 or later - This is required for perl and python language support. Without it, perl, python, and the GUI will not work.
• perl - Support for writing scripts in the perl language that use the OpenIPMI library.
• python - Support for writing scripts in the python language that use the OpenIPMI library.
• Tcl/Tk - There is no Tcl language support (someone may contribute that, though). However, A Tcl OS handler is provided so that Perl and Python may use the Tk widgets. Without this, the GUI will not work. Note that getting Tcl/Tk to work right can be difficult, see below for more details.
• Tkinter/Tix - Python GUI libraries. Required for the GUI to work.
• gdbm - This is used on *nix for local SDR caching. This is not required, but it really speeds up startup.

Note you need to install the development packages (generally ending in -dev) of most of these for OpenIPMI to pick it up. You can examine the output of configure to make sure they are properly discovered.

Tcl is installed in various places, and the configure script probably won't find it. If it doesn't, you must specify the install location for Tcl by adding: --with-tclcflags=flags --with-tcllibs=lib For instance, on my Debian Linux system, I have to specify: ./configure --with-tclcflags="-I /usr/include/tcl8.4" --with-tcllibs=-ltcl8.4 to make it work right.

If you don't get this right, you don't get a GUI!

ipmish is a command interpreter that lets you execute IPMI operations, get the results, etc. It gives you the full power of OpenIPMI. It can easily be driven with a TCL script or the like. See the man page for more details.

The GUI is cleverly named openipmigui and provides a GUI interface to most of OpenIPMI. It also has the standard command language (like ipmish) available in a window, so it has all the power of ipmish.

To use the GUI, you have to have the following optional packages:

• swig 1.3.21 or later
• python
• Tcl/Tk
• Tkinter/Tix

The GUI is documented in the openipmigui man page.

ipmi_ui is a cheesy little tool that runs on top of the OpenIPMI library. It provides a command line and text-window based view into an IPMI system. A man page is included for it, if you want to know more.

Note that ipmi_ui was written primarily for testing. It does things that users generally shouldn't do. You can use it for examples, but it touches things that are considered OpenIPMI internal, so be careful what you use. ipmish and the sample code is a much better example.

OpenIPMI has perl and python bindings using swig. The public interface of OpenIPMI is available, but the private interfaces are not (and a few other things like SNMP trap support). It is fully function.

I was hoping that swig would generate documentation from the comments, but it turns out that it does not do that. You can look at swig/OpenIPMI.i for the documentation on all the interfaces, and swig/perl/sample and the gui in swig/python/openipmigui.py for a piece of sample code that uses most of the interfaces.

The interface is object-oriented, so you have to know how to do OO Perl or Pythong to use this. It is like this because that is the most natural way to use SWIG (and it makes more OO languages like python easier).

The OpenIPMI ipmi_ui command has an optional trap handler. It will use incoming traps as an indication that something is waiting in the SEL for it to fetch and immediately start a fetch. You have to have the UCD snmp library (or something compatible) installed for this to work, and you have to start ipmi_ui with the '-snmp' option. You must do this as root, as the SNMP Trap port is 162.

You may ask why the trap is not directly used, why does it just trigger an SEL fetch? Well, that's because the IPMI trap does not have enough information to determine the correct sensor (it's missing the channel and LUN) and it does not have enough information to correlate the SEL entries with the trap (It doesn't have the record ID or necessarily the proper timestamp).

Also, OpenIPMI does not directly handle the traps. Instead, it has an interface to report a trap when it has been received. OpenIPMI does not want to assume the SNMP library being used; instead it lets the user pick that library. If you want an example of how to use the UCD SNMP or NET SNMP libraries and hook them into OpenIPMI, the ui/basic_ui.c file has an example of this.

It does include the utility "ipmicmd" which lets you do direct IPMI commands to a connection. ipmicmd can connect using the OpenIPMI driver or via IPMI LAN.

OpenIPMI also includes a LAN to system interface converter, it can sit on top of an OpenIPMI driver and supply a LAN connection to the BMC. Note that to work the best, the LAN converter needs at least the v22 version of the OpenIPMI driver to support setting retries and timeouts for messages.

Other sample code for using OpenIPMI is in the "samples" directory.

OpenIPMI includes a texinfo document in the "doc" directory. It talks a little about IPMI, must mostly about OpenIPMI. It is required reading for using OpenIPMI. Read it carefully.

Unfortunately, the IPMI spec is also currently required reading for using OpenIPMI. Fortunately, you do not need to read the whole spec. If you read the OpenIPMI document first, you can probably get by with reading the following sections in the 1.5 spec:

• 1.6 (overview)
• 5.2 (for the error completion codes)
• 33-36 (talking about sensors and entities)
• 37.1 (talking about the main sensor SDR, mostly for learning about sensor capabilities). OpenIPMI should hide the rest from you.

The OpenIPMI document is currently just an overview. It should point you in all the right directions, but it does not contain the actual details of most OpenIPMI functions. Those are currently documented in the include files, so you will have to look through the include files for how to use the functions.