README

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

What is IPMI?
=============

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.


What is OpenIPMI?
=================

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.


Building and Configuring OpenIPMI
=================================

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=<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=<path>' 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.


Getting Tcl/Tk to work
======================

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!


Using ipmish
============

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 OpenIPMI GUI
================

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.


Using ipmi_ui
=============

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.


Perl/Python and OpenIPMI
========================

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).


OpenIPMI and SNMP
=================

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.


What Else Comes with OpenIPMI?
==============================

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.


IPMI Documentation
==================

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.


OpenIPMI Source Structure
=========================

Note that parts of OpenIPMI could be used inside other systems.
However, the LGPL license may be a restriction.  If you are interested
in re-licensing parts of OpenIPMI, contact MontaVista software.

The source tree here consists of the following directories:

+---cmdlang - A command-line interpreter that gives access to the
|             OpenIPMI library.  Includes a user interface named
|             openipmish that demonstrates how to use it.
|  
+--- doc - The main documentation for OpenIPMI
|
+---glib - A glib OS handler.
|  
+---include
|   +---linux - linux-specific include files
|   \---OpenIPMI - User-visible include files for OpenIPMI
|       \---internal - Internal include files, only for plugins
|
+---lanserv - Code to provide a LAN interface to an IPMI device and
|             to provide an IPMI simulator
|  
+---lib - The man OpenIPMI code.  This is where all the logic for the
|         handling of IPMI messages is.
|  
+---man - The man pages for the 
|
+---sample - Sample code and utilities that use the OpenIPMI library.
|  
+---swig - The main interpreter interface.  swig is a program that
|   |      takes a general description of a C/C++ interface and
|   |      provides the equivalent interface in various interpreters.
|   +---perl - Perl-specific code for swig, including sample code and
|   |          tests.
|   \---python - Python-specific code for swig.
|       \---openipmigui - A GUI for OpenIPMI, written in Python.
|
+---tcl - A TCL OS handler
|
+---ui - A depracated UI for OpenIPMI.
|  
+---unix - A POSIX OS handler, one for threaded and one for
|          non-threaded applications/
|  
\---utils - General utility code used by both the OpenIPMI library
            and by the lanserv code.