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 like it. 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 message commands. 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 testing. 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 commands. 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 interface. 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 entity information. * Manages access to the SEL. * Handles the interface, which is especially hard for LAN connections. * 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 library. 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 them, though. 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 in OpenIPMI? 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 system. 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 sure. 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 like easier. 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() and friends. * 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 manual. * 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.