\input texinfo @c -*-texinfo-*-
@c This file uses the @command command introduced in Texinfo 4.0.
@c %**start of header
@setfilename freeipmi-faq.info
@settitle FreeIPMI - Frequently Asked Questions
@finalout
@c %**end of header

@include version-faq.texi

@copying
This manual is for FreeIPMI (version @value{VERSION}, @value{UPDATED}).
Copyright @copyright{} 2006-2012 FreeIPMI Core Team

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
@end quotation
@end copying

@dircategory Platform Management
@direntry
* FreeIPMI FAQ: (freeipmi-faq).  FreeIPMI - Frequently Asked Questions
@end direntry

@ifinfo
Copyright @copyright{} 2003-2012 FreeIPMI Core Team.


@end ifinfo

@titlepage
@title FreeIPMI Frequently Asked Questions
@subtitle Free Intelligent Platform Management System
@subtitle Version @value{VERSION} updated on @today{}
@author by Albert Chu @email{chu11@@llnl.gov}
@c @author by Anand Babu @email{ab@@gnu.org.in}

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 2003-2012 FreeIPMI Core Team
@insertcopying
@end titlepage


@node Top, What is IPMI?, (dir), (dir)
@ifinfo
Frequently Asked Questions on @strong{FreeIPMI}

This edition of the documentation was last updated on @today{} for
release @value{VERSION} of the FreeIPMI.
@end ifinfo

@menu
* What is IPMI?::
* What is FreeIPMI?::
* How did FreeIPMI start?::
* What operating systems does FreeIPMI run on?::
* FreeIPMI vs OpenIPMI vs Ipmitool vs Ipmiutil::
* What is special about FreeIPMI?::
* Does my system support IPMI?::
* How do I compile FreeIPMI?::
* libgcrypt requirement::
* x86-64 Compilation::
* Installing FreeIPMI on FreeBSD::
* What are some IPMI terminology or acronyms I should be aware of?::
* What setup is needed for FreeIPMI to communicate over LAN?::
* What setup is needed for Serial over LAN (SOL) or Ipmiconsole?::
* Do I need to install or configure a driver to perform IPMI inband?::
* SSIF Driver Configuration::
* How do you setup Powerman with ipmipower?::
* How do you setup Conman with ipmiconsole or libipmiconsole?::
* How do you setup Ganglia or Nagios to monitor IPMI sensors via FreeIPMI?::
* Why are times reported by FreeIPMI tools wrong?::
* Why is the IPMI kernel driver faster than the KCS driver?::
* Why is the output from FreeIPMI different than another software?::
* Why are there so many IPMI compliance bugs?::
* How do I get around an IPMI compliance bug on my motherboard?::
* Why am I seeing so many 'internal IPMI error' or 'driver busy' messages?::
* How do I program with the FreeIPMI libraries?::
* Where can I get additional help or support?::
@end menu

@c Output the table of contents at the beginning.
@contents

@node What is IPMI?, What is FreeIPMI?, Top, Top
@section What is IPMI?

The @acronym{IPMI} specifications define standardized, abstracted
interfaces to the platform management subsystem.  @acronym{IPMI}
includes the definition of interfaces for extending platform
management between the board within the main chassis and between
multiple chassis.

The term platform management is used to refer to the monitoring and
control functions that are built in to the platform hardware and
primarily used for the purpose of monitoring the health of the system
hardware.  This typically includes monitoring elements such as system
temperatures, voltages, fans, power supplies, bus errors, system
physical security, etc.  It includes automatic and manually driven
recovery capabilities such as local or remote system resets and power
on/off operations.  It includes the logging of abnormal or
out-of-range conditions for later examination and alerting where the
platform issues the alert without aid of run-time software.  Lastly it
includes inventory information that can help identify a failed
hardware unit.

@node What is FreeIPMI?, How did FreeIPMI start?, What is IPMI?, Top
@section What is FreeIPMI?

FreeIPMI is a collection of Intelligent Platform Management
@acronym{IPMI} system software.  It provides in-band and out-of-band
software and a development library conforming to the Intelligent
Platform Management Interface (@acronym{IPMI} v1.5 and v2.0)
standards.  FreeIPMI also supports @acronym{IPMI}-related
specifications such as the Data Center Management Interface
(@acronym{DCMI}) and Intel Node Manager.

@node How did FreeIPMI start?, What operating systems does FreeIPMI run on?, What is FreeIPMI?, Top
@section How did FreeIPMI start?

In October 2003, California Digital Corp. (CDC) was contracted by
Lawrence Livermore National Laboratory (@acronym{LLNL}) for the assembly of
Thunder, a 1024 node Itanium2 cluster.  This led to software
developers from CDC and @acronym{LLNL} merging the @acronym{IPMI} software
developed by both organizations into FreeIPMI.

Anand Babu, Balamurugan and Ian Zimmerman at CDC contributed the
in-band @acronym{KCS} driver, @command{ipmi-sensors},
@command{ipmi-sel}, @command{bmc-info}, core portions of @command{ipmi-config}, and
portions of libfreeipmi.  Albert Chu and Jim Garlick at @acronym{LLNL}
contributed @command{ipmipower}, @command{bmc-watchdog},
@command{ipmiping}, @command{rmcpping}, portions of libfreeipmi, and
@acronym{IPMI} support in Powerman.  In October 2004, FreeIPMI 0.1.0
was officially released.

Since the 0.1.0 release, Z Research developers have contributed
@command{ipmi-chassis}, @command{ipmi-raw}, @command{ipmi-locate}, and
PEF portions of @command{ipmi-config}.  @acronym{LLNL} has contributed
@acronym{IPMI} 2.0 support, hostrange support, @command{ipmiconsole},
libipmiconsole, @command{ipmidetect}, @command{bmc-device},
@command{ipmi-oem}, @command{ipmi-dcmi}, libipmimonitoring, and the
chassis and sensor portions of @command{ipmi-config}.

(Note: The original FreeIPMI developers from California Digital
Corp. are now at Zresearch Inc.)

@node What operating systems does FreeIPMI run on?, FreeIPMI vs OpenIPMI vs Ipmitool vs Ipmiutil, How did FreeIPMI start?, Top
@section What operating systems does FreeIPMI run on?

FreeIPMI was originally developed on GNU/Linux.  It has been confirmed
to be built on most major GNU/Linux distributions such as Redhat,
Fedora, Suse, and Debian.  FreeIPMI has been ported and confirmed to
work on atleast FreeBSD, OpenBSD, Solaris, OpenSolaris, and Windows
via Cygwin.  We imagine it would build cleanly on other operating
systems.  If it doesn't, it should be easily portable to them.  Please
contact the maintainers on the @email{freeipmi-devel@@gnu.org} mailing
lists.

@node FreeIPMI vs OpenIPMI vs Ipmitool vs Ipmiutil, What is special about FreeIPMI?, What operating systems does FreeIPMI run on?, Top
@section FreeIPMI vs OpenIPMI vs Ipmitool vs Ipmiutil

There are multiple implementations, APIs, interfaces, end user
requirements, etc. that one can choose when developing @acronym{IPMI}
drivers, libraries, and tools.  FreeIPMI has taken some different
approaches than other open-source projects.

The section below points out a number of the reasons why we feel
FreeIPMI is particularly special compared to the other projects.

The Ipmiutil project has a good chart describing many of the
differences between the projects:
@uref{http://ipmiutil.sourceforge.net/docs/ipmisw-compare.htm}.

@node What is special about FreeIPMI?, Does my system support IPMI?, FreeIPMI vs OpenIPMI vs Ipmitool vs Ipmiutil, Top
@section What is special about FreeIPMI?

In our eyes, there are several reasons why FreeIPMI is particularly special.

@enumerate

@item Support for HPC, clusters, and large data centers

A number of features have been added into the tools to support HPC,
clusters, and/or large data centers.  Much of this original support
was added to support the large cluster environments at Lawrence
Livermore National Laboratory (@acronym{LLNL}).

Scalable parallel execution of many FreeIPMI tools
(@command{ipmi-sensors}, @command{ipmi-sel}, @command{bmc-info}, etc.)
across a cluster is supported through hostranged input and output.
For example:

@example
# > bmc-info -h "pwopr[0-5]" -u XXX -p XXX --get-device-id -C
----------------
pwopr[0-1,5]
----------------
Device ID             : 34
Device Revision       : 1
Device SDRs           : unsupported
Firmware Revision     : 1.0c
Device Available      : yes (normal operation)
IPMI Version          : 2.0
Sensor Device         : supported
SDR Repository Device : supported
SEL Device            : supported
FRU Inventory Device  : supported
IPMB Event Receiver   : unsupported
IPMB Event Generator  : unsupported
Bridge                : unsupported
Chassis Device        : supported
Manufacturer ID       : Peppercon AG (10437)
Product ID            : 4
Auxiliary Firmware Revision Information : 38420000h
----------------
pwopr[2-4]
----------------
Device ID             : 34
Device Revision       : 1
Device SDRs           : unsupported
Firmware Revision     : 1.17
Device Available      : yes (normal operation)
IPMI Version          : 2.0
Sensor Device         : supported
SDR Repository Device : supported
SEL Device            : supported
FRU Inventory Device  : supported
IPMB Event Receiver   : unsupported
IPMB Event Generator  : unsupported
Bridge                : unsupported
Chassis Device        : supported
Manufacturer ID       : Peppercon AG (10437)
Product ID            : 4
Auxiliary Firmware Revision Information : 38420000h
@end example

In the above example, its clear to see that pwopr[2-4] have different
firmware than pwopr[0-1,5].  More information about hostrange support
can be found in the document @file{freeipmi-hostrange.txt}
(@uref{http://www.gnu.org/software/freeipmi/freeipmi-hostrange.txt}).

@command{Ipmipower} is capable of scaling to large nodes for cluster support and
is supported by Powerman
(@uref{https://github.com/chaos/powerman}) for scalable power
management.  At @acronym{LLNL}, in conjunction with Powerman, ipmipower is used
for power control on clusters ranging from sizes of 4 to 2000.  It has
been used to determine power status or power control @acronym{LLNL}'s largest
clusters in under a second.

@command{libipmiconsole} is currently supported by Conman
(@uref{https://github.com/dun/conman}) and Conserver (@uref{http://www.conserver.com/}) for scalable console management.

@command{Ipmi-sensors} and libipmimonitoring are capable of
interpreting sensor readings as well as just reporting them.  It can
be used for host monitoring @acronym{IPMI} sensor severity on a
cluster.  By mapping sensor readings into NOMINAL, WARNING, or
CRITICAL states, it makes monitoring sensors easier across large
numbers of nodes.  Skummee
(@uref{http://sourceforge.net/projects/skummee}) currently uses
libipmimonitoring to monitoring sensors on @acronym{LLNL} clusters of
up to 2000 nodes in size.  FreeIPMI sensor monitoring plugins for
Ganglia (@uref{http://ganglia.info/}) and Nagios
(@uref{http://www.nagios.org/}) have also been developed and made
available for download
(@uref{http://www.gnu.org/software/freeipmi/download.html}).

@command{Ipmi-sel} and libipmimonitoring are capable of interpreting
system event log (@acronym{SEL}) entries as well as just reporting
them.  It can be used for host monitoring @acronym{IPMI} event
severity on a cluster.  By mapping events into NOMINAL, WARNING, or
CRITICAL states, it makes monitoring system events easier across large
numbers of nodes.  Skummee
(@uref{http://sourceforge.net/projects/skummee}) currently uses
libipmimonitoring to monitoring the @acronym{SEL} on @acronym{LLNL}
clusters of up to 2000 nodes in size.

The @command{ipmi-config} configuration file and command-line
interface are used to easily copy the @acronym{BMC} configuration from
one node to every other node in a cluster quickly.  It has been used
to modify the @acronym{BMC} configuration across large @acronym{LLNL}
clusters in a few minutes.  They also have the capability to verify
(via the diff option) that the desired configuration has been properly
stored to firmware.

@command{Ipmidetect} can be used to enhance the efficiency of the hostranged
input by eliminating those nodes in the cluster that have been
temporarily removed for servicing.

FreeIPMI is supported within Slurm for energy consumption monitoring.

@item Additional @acronym{OEM} support

FreeIPMI contains support for a number of @acronym{OEM} extensions and @acronym{OEM}
sensors and/or events.  @command{Ipmi-oem} currently supports @acronym{OEM}
command extensions for motherboards made by Dell, Fujitsu, IBM, Intel,
Inventec, Quanta, Sun Microsystems, Supermicro, and Wistron.
@command{Ipmi-sensors} and @command{ipmi-sel} support @acronym{OEM} sensors
and/or events for motherboards made from Dell, Fujitsu, HP, Intel,
Inventec, Quanta, Sun Microsystems, Supermicro, and Wistron.  (Some of
the motherboards may have been rebranded by vendors, see manpages for
official list of confirmed supported motherboards.)

@item Additional flexibility and features

By implementing various @acronym{IPMI} sub-sections into multiple
tools, each tool is capable of providing the user with more
flexibility and ultimately more features in addition to those listed
above.  It may not be as easy (or architecturally possible) to do in
an all-in-one tool.

@item Extra @acronym{IPMI} support

In addition to the features listed above, FreeIPMI also supports
specifications related to @acronym{IPMI}.  The Data Center Management
Interface, or @acronym{DCMI}, is supported via the FreeIPMI tool
@command{ipmi-dcmi}.  Some aspects of the Intel Power Node Manager are
supported in @command{ipmi-oem}.

@item Easy setup

By implementing drivers in userspace libraries, there is no need to
build/setup/manage any kernel modules/drivers.

@item Portability

Likewise, by implementing everything in userspace libraries and tools,
portability to multiple operating systems and architectures should be
easier.

@end enumerate

@node Does my system support IPMI?, How do I compile FreeIPMI?, What is special about FreeIPMI?, Top
@section Does my system support IPMI?

Unfortunately, there are no universally defined mechanisms for
determining if a system supports @acronym{IPMI} via Inband
communication.  Assuming IPMI is set up correctly for over LAN
communication, a fairly reliable mechanism exists out-of-band.  Here
are some suggestions.

@enumerate

@item
FreeIPMI's @command{ipmi-locate} can be used to determine if
@acronym{IPMI} can be found on your system.  Users are cautioned
though, the failure to discover @acronym{IPMI} via
@command{ipmi-locate} is not sufficient to disprove that
@acronym{IPMI} exists on your system.  Your system may not publish
such information or may expect clients to communicate at default
locations.

@item
@command{dmidecode} may be similarly used to probe for devices that
support @acronym{IPMI} on your system.  You may grep for
@acronym{IPMI} or specify the @acronym{IPMI} DMI type on the
command line.

@example
# > dmidecode --type 38
# dmidecode 2.10
SMBIOS 2.5 present.

Handle 0x0049, DMI type 38, 18 bytes
IPMI Device Information
        Interface Type: KCS (Keyboard Control Style)
        Specification Version: 2.0
        I2C Slave Address: 0x10
        NV Storage Device: Not Present
        Base Address: 0x0000000000000CA2 (I/O)
        Register Spacing: Successive Byte Boundaries
@end example

@item
FreeIPMI's @command{ipmi-ping} can be used to see if a machine has an
IPMI service at a specific host/IP address.  For more wide scale IPMI
discovery, the @command{ipmi-detectd} daemon and @command{ipmi-detect}
tool can be used.

@end enumerate

Again, the failure to find an @acronym{IPMI} supported device is not
sufficient to show lack of @acronym{IPMI} support.

Ultimately, some amount of information from product documents or trial
and error may be necessary to determine if @acronym{IPMI} is supported
on your system.

@node How do I compile FreeIPMI?, libgcrypt requirement, Does my system support IPMI?, Top
@section How do I compile FreeIPMI?

Please see the README.build instructions provided with FreeIPMI or on
the FreeIPMI website's documentation
(@uref{http://www.gnu.org/software/freeipmi/README.build}).

@node libgcrypt requirement, x86-64 Compilation, How do I compile FreeIPMI?, Top
@section libgcrypt requirement

FreeIPMI requires the libgcrypt library to be installed for a variety
of encryption requirements in @acronym{IPMI} 2.0.  If you are building
FreeIPMI and receive a 'libgcrypt required to build libfreeipmi'
error, please install libgcrypt.  For Linux users, this may require
the install of the libgcrypt-devel package as well.  For those who do
not need @acronym{IPMI} 2.0 encryption, FreeIPMI may be built without
it by specifying @option{--without-encryption} when executing
configure.

@node x86-64 Compilation, Installing FreeIPMI on FreeBSD, libgcrypt requirement, Top
@section x86-64 Compilation

By default, FreeIPMI's build autotools (e.g. configure) should detect
if you are on a 64 bit system and should build against 64 bit
libraries.  However, some multi-architecture installs (e.g. you have
32 bit and 64 bit libraries installed) may lead to builds and installs
of 32 bit instead of 64 bit.  For those noticing this, pass libdir
appropriately to the configure script to workaround this
problem. (e.g. @option{--libdir=/usr/lib64})

Example:
@example
  # ./configure  --prefix=/usr --libdir=/usr/lib64
@end example

@node Installing FreeIPMI on FreeBSD, What are some IPMI terminology or acronyms I should be aware of?, x86-64 Compilation, Top
@section Installing FreeIPMI on FreeBSD

You can install a binary package of freeipmi or use the port, located
in ports/sysutils/freeipmi, to build it from the source. See ports(7)
and 'Packages and Ports' section
(@uref{http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/ports.html})
in The FreeBSD Handbook.

Please contact port maintainer (MAINTAINER line in the port's Makefile),
if you have problems building from the port.

@node What are some IPMI terminology or acronyms I should be aware of?, What setup is needed for FreeIPMI to communicate over LAN?, Installing FreeIPMI on FreeBSD, Top
@section What are some IPMI terminology or acronyms I should be aware of?

Good question, here are some terms and acronyms with general
definition you might want to know.

@table @strong

@item BMC

The @strong{Baseboard Management Controller} is the management chip on
the system that is responsible for @acronym{IPMI}.  It is common to
refer to configuring the ``@acronym{BMC}'' as synonymous for
configuring @acronym{IPMI}.

@item inband

@strong{inband} @acronym{IPMI} communication refers to communication
on a system locally (i.e. not over a network).

@item outofband

@strong{outofband} and @strong{IPMI over LAN} refer to @acronym{IPMI}
communication over a network, typically ethernet.

@item SDR

The @strong{Sensor Data Repository} is a database of system
information that is needed by many other @acronym{IPMI} functions.  It
is commonly read before some @acronym{IPMI} action can be taken.  For
example, it contains a list of all sensors on a system, so it must be
downloaded before sensors on a system can be read.  In FreeIPMI, the
@acronym{SDR} is cached in a common location and can be used by a
number of tools, such as @command{ipmi-sensors}, @command{ipmi-sel},
and @command{ipmi-fru}.

@item SEL

The @strong{System Event Log} is a log of events stored on the system
for later diagnostics.  In FreeIPMI, @command{ipmi-sel} can be used to
read the @acronym{SEL}.

@item FRU

The @strong{Field Replaceable Unit} is a general computing term
refering to a replaceable unit of electronics.  In @acronym{IPMI} it is
common to refer to the ``@acronym{FRU}'' as the database of all
@acronym{FRU} components on a system.  In FreeIPMI, @command{ipmi-fru}
can be used to read the @acronym{FRU} components on a system.

@item PEF

@strong{Platform Event Filtering} refers to the rules that determine
when PETs are generated and where they are sent.  In FreeIPMI,
@acronym{PEF} can be configured via @command{ipmi-config}.

@item PET

@strong{Platform Event Trap} refers to a trap that can be sent by a
system to an SNMP agent to indicate an event has occurred on the
system.  In FreeIPMI, a @acronym{PET} trap can be interpreted via
@command{ipmi-pet}.

@item DCMI

The @strong{Data Center Management Interface} is a management
interface defined by a group of vendors that use @acronym{IPMI} as the
backend for their system management definition.  In FreeIPMI,
@command{ipmi-dcmi} can be used to read/configuring @acronym{DCMI}.

@item SOL

@strong{Serial over LAN} refers to the forwarding of serial system
traffic over a network, typically an ethernet network.  It is
typically used to access a remote system console.  In FreeIPMI,
ipmiconsole is used to access a remote console via @acronym{SOL}.

@item RMCP

The @strong{Remote Management Control Protocol} protocol is another
remote management protocol which @acronym{IPMI} is defined within for
outofband communication.  For most @acronym{IPMI} users, you will
never need to know about @acronym{RMCP}.

@end table

@node What setup is needed for FreeIPMI to communicate over LAN?, What setup is needed for Serial over LAN (SOL) or Ipmiconsole?, What are some IPMI terminology or acronyms I should be aware of?, Top
@section What setup is needed for FreeIPMI to communicate over LAN?

Please see the ipmi-config.conf(5) manpage provided with FreeIPMI for
details, or you can read it on the FreeIPMI website's documentation
(@uref{http://www.gnu.org/software/freeipmi/manpages/man5/ipmi-config.conf.5.html}).

@node What setup is needed for Serial over LAN (SOL) or Ipmiconsole?, Do I need to install or configure a driver to perform IPMI inband?, What setup is needed for FreeIPMI to communicate over LAN?, Top
@section What setup is needed for Serial over LAN (SOL) or Ipmiconsole?

The setup of Serial-over-LAN (@acronym{SOL}) and/or
@command{Ipmiconsole} is highly dependent on your system.  However,
most motherboardss require the following:

@enumerate

@item
Adjust the BIOS COM port for serial redirection over @acronym{SOL}
instead of the normal serial port and set the appropriate baud rate.
If you do not know which port is the @acronym{SOL} port, you may need
to play around and guess.  It is likely a non-default setting, since
many manufacturers may still assume the default redirection is out of
the normal serial port.  If you do not have a serial port on your
motherboard, this part can probably be skipped.

@item
Configure @acronym{IPMI} on the motherboard to use @acronym{SOL}.
Many motherboards may have this enabled by default, however you may
wish to verify with FreeIPMI's @command{ipmi-config}.  More information
can be found in the ipmi-config.conf(5) manpage on the settings.
However, the key settings are to enable @acronym{SOL} on the system,
enable @acronym{SOL} for individual users, and select the appropriate
baud.  On many motherboards, the selected baud must match what is
configured in the BIOS.

@item
Adjust your operating systems serial console settings to use the
appropriate COM port.  For Linux, the following guide
(@uref{http://www.vanemery.com/Linux/Serial/serial-console.html})
provides a pretty good overview of setting of a serial console on
Linux.  The only difference for setting up a serial console with
@command{Ipmiconsole} or @acronym{SOL}, is the ttySX terminal may need to be
changed.

@end enumerate

@node Do I need to install or configure a driver to perform IPMI inband?, SSIF Driver Configuration, What setup is needed for Serial over LAN (SOL) or Ipmiconsole?, Top
@section Do I need to install or configure a driver to perform IPMI inband?

For most people the answer is no.

FreeIPMI includes a userspace driver that works on most motherboards
without any driver installation, loading, or configuration required.
FreeIPMI also includes support of a Linux SSIF driver through the SSIF
device (i.e. @file{/dev/i2c-0}), the OpenIPMI Linux kernel driver
(i.e. @file{/dev/ipmi0}), the Sun/Solaris @acronym{BMC} driver
(i.e. @file{/dev/bmc}), and the Intel @acronym{DCMI}/MEI driver
(i.e. @file{/dev/dcmi}).  If you communicate through one of these
mechanisms, the appropriate drivers for them should be loaded.  Most
systems should automatically load the appropriate drivers you need.

Under most scenarios, the FreeIPMI tools should automatically discover
which in-band interface to use and the proper settings to use.  Some
motherboards may require you to determine alternate configurations for
addresses, paths, etc. on your own and pass them as command line
options to the tools.

Every system is different and your situation may differ.  Please see
your manufacturer and operating system instructions.

Special note: At the time of this writing the Intel DCMI/MEI Linux
device drivers are not distributed widely.  Please work with your
vendor to obtain the Intel MEI and DCMI device drivers.

There are some additional Linux OpenIPMI kernel driver notes here:
@uref{http://www.gnu.org/software/freeipmi/README.openipmi}.

@node SSIF Driver Configuration, How do you setup Powerman with ipmipower?, Do I need to install or configure a driver to perform IPMI inband?, Top
@section SSIF Driver Configuration

FreeIPMI's SSIF driver works on top of kernel'2 i2c device
interface.

Under GNU/Linux load these kernel modules: i2c-dev, i2c-i801, i2c-core
before using FreeIPMI.

To identify SSIF device address:

Example:
@example
$> lspci  (in the output look for this entry)
 00:1f.3 SMBus: Intel Corp. 6300ESB SMBus Controller (rev 01)
       Subsystem: Intel Corp.: Unknown device 342f
       Flags: medium devsel,  IRQ 17
       I/O ports at 0400 [size=32]
                    ----
$> cat /proc/bus/i2c
i2c-0   smbus    SMBus I801 adapter at 0400         Non-I2C SMBus adapter
                                       ----
    Make sure the "0400" above matches with the "0400" address under
    proc.  Also make sure "i2c-0" is not different. If it appears
    different then grep for "i2c-0" in this code "ipmitool.c" and
    change. "i2c-X" is the label assigned to each slave device attached on
    the i2c bus.

BMC address Locator:
    Refer to the SM BIOS IPMI Device Information Record
    Type 38,  record 06h and 08h. Use the value of record
    06h as the IPMBAddress and load the SMBus controller
    driver at the address value read from record 08h.

    Usual values for record 06h -> 0x42
    Usual values for record 08h -> 0x400
@end example

@node How do you setup Powerman with ipmipower?, How do you setup Conman with ipmiconsole or libipmiconsole?, SSIF Driver Configuration, Top
@section How do you setup Powerman with ipmipower?

There are additional details in the Powerman
(@uref{https://github.com/chaos/powerman}) documentation, however
here are the basics.  In the powerman.conf file, you want to include
the @file{ipmipower.dev} device file, setup an ipmipower device in
co-process mode, then configure hosts to use that device.

@example
include "/etc/powerman/ipmipower.dev"

device "ipmi0" "ipmipower" "/usr/sbin/ipmipower -h mynodes[0-10] |&"

node "mynodes[0-10]"  "ipmi0" "mynodes[0-10]"
@end example

You may wish to add some additional ipmipower configuration on the
device line:

@example
device "ipmi0" "ipmipower" "/usr/sbin/ipmipower --wait-until-on --wait-until-off -h mynodes[0-10] -u username -p password |&"
@end example

although you will probably want to do some of this configuration
(especially the username and password) in @file{freeipmi.conf}.

If you use an alternate set of hostnames for @acronym{IPMI} from the
primary hostname, that can configured like this:

@example
device "ipmi0" "ipmipower" "/usr/sbin/ipmipower -h altname[0-10] |&"

node "primaryname[0-10]"  "ipmi0" "altname[0-10]"
@end example

Configuration can be trickier if you want to configure Powerman to use
ipmipower with an @acronym{OEM} extension specified through
@option{--oem-power-type}.  Many @acronym{OEM} extensions in ipmipower must
include additional arguments, which can be passed in via the node
argument.  In addition, while @command{ipmipower} can take a host
range as an additional argument, Powerman may not.

For example, the following would be suitable to configure @acronym{OEM}
extension support the Dell Poweredge C410x.  A specific node
identifier is used to map to a specific node and additional argument
(i.e. mynodes0-1 maps to mynodes0+1).

@example
include "/etc/powerman/ipmipower.dev"

device "ipmi0" "ipmipower" "/usr/sbin/ipmipower -h mynodes[0-10]+[1-16] --oem-power-type=c410x -l admin |&"

node "mynodes[0-10]-1" "ipmi0" "mynodes[0-10]+1"
node "mynodes[0-10]-2" "ipmi0" "mynodes[0-10]+2"
node "mynodes[0-10]-3" "ipmi0" "mynodes[0-10]+3"
node "mynodes[0-10]-4" "ipmi0" "mynodes[0-10]+4"
node "mynodes[0-10]-5" "ipmi0" "mynodes[0-10]+5"
node "mynodes[0-10]-6" "ipmi0" "mynodes[0-10]+6"
node "mynodes[0-10]-7" "ipmi0" "mynodes[0-10]+7"
node "mynodes[0-10]-8" "ipmi0" "mynodes[0-10]+8"
node "mynodes[0-10]-9" "ipmi0" "mynodes[0-10]+9"
node "mynodes[0-10]-10" "ipmi0" "mynodes[0-10]+10"
node "mynodes[0-10]-11" "ipmi0" "mynodes[0-10]+11"
node "mynodes[0-10]-12" "ipmi0" "mynodes[0-10]+12"
node "mynodes[0-10]-13" "ipmi0" "mynodes[0-10]+13"
node "mynodes[0-10]-14" "ipmi0" "mynodes[0-10]+14"
node "mynodes[0-10]-15" "ipmi0" "mynodes[0-10]+15"
node "mynodes[0-10]-16" "ipmi0" "mynodes[0-10]+16"
@end example

As noted in the manpage, the Dell Poweredge C410x appears to have
difficulty handling new slot power control requests until prior ones
have completed.  Users may wish to configure @command{ipmipower} with
@option{--wait-until-on}, @option{--wait-until-off}, and consider
using the @file{ipmipower-serial.dev} device file instead of
@file{ipmipower.dev}.

@node How do you setup Conman with ipmiconsole or libipmiconsole?, How do you setup Ganglia or Nagios to monitor IPMI sensors via FreeIPMI?, How do you setup Powerman with ipmipower?, Top
@section How do you setup Conman with ipmiconsole or libipmiconsole?

There are additional details in the Conman
(@uref{https://github.com/dun/conman}) documentation and manpages,
however here are some basics.

To configure Conman to connect via the ipmiconsole tool, Conman comes
with an expect script named ipmiconsole.exp, typically installed into
@file{/usr/lib/conman/exec/ipmiconsole.exp}.  Consoles can be setup by
adding lines to @file{conman.conf} like:

@example
CONSOLE name="myserver"   dev="/usr/lib/conman/exec/ipmiconsole.exp myserver myusername mypassword"
@end example

One of the useful aspects of using the ipmiconsole.exp script is that
the same configuration options you may have already configured into
@file{freeipmi.conf}, may be loaded automatically when ipmiconsole is
executed via this expect script.

However, as can be expected, scalability may be a problem as you must
launch a process for every node in your cluster.

Conman is also capable of connecting to servers natively through the
libipmiconsole library, so that no additional processes are launched.
They can be configured as follows:

@example
CONSOLE name="myserver" IPMIOPTS="U:myusername,P:mypassword" dev="ipmi:myserver"
@end example

on some older versions of Conman, you would instead use

@example
CONSOLE name="myserver" IPMIOPTS="myusername,mypassword" dev="ipmi:myserver"
@end example

Please see the Conman documentation for current version options and
additional configuration options available.  Alternate defaults for
libipmiconsole can also be set via the @file{libipmiconsole.conf}
file.

One of the additional advantages of configuring Conman to use the
libipmiconsole library natively is that Conman is able to detect and
manage additional @acronym{IPMI} error cases.

@node How do you setup Ganglia or Nagios to monitor IPMI sensors via FreeIPMI?, Why are times reported by FreeIPMI tools wrong?, How do you setup Conman with ipmiconsole or libipmiconsole?, Top
@section How do you setup Ganglia or Nagios to monitor IPMI sensors via FreeIPMI?

Scripts to monitor @acronym{IPMI} via FreeIPMI in Ganglia and Nagios
have been developed and are downloadable on the FreeIPMI homepage
(@uref{http://www.gnu.org/software/freeipmi/download.html}).
Instructions for setup can be found at the top of the scripts.

@node Why are times reported by FreeIPMI tools wrong?, Why is the IPMI kernel driver faster than the KCS driver?, How do you setup Ganglia or Nagios to monitor IPMI sensors via FreeIPMI?, Top
@section Why are times reported by FreeIPMI tools wrong?

Times reported by various FreeIPMI tools (such as @command{ipmi-sel})
are reported under the assumption that timestamps are written in
localtime.  This is by definition in the IPMI specification.

Whether or not a system truly stored the timestamps in localtime
varies on many factors, such as the vendor, BIOS, and operating
system.

If the times reported by the tool are off, there is a strong
likelihood the time may be stored in GMT/UTC and needs to be converted
into localtime.  In FreeIPMI tools that have time outputs, the
@option{--utc-to-localtime} option can be specified or the
@option{utc-to-localtime} option can be specified in
@file{freeipmi.conf}.

@node Why is the IPMI kernel driver faster than the KCS driver?, Why is the output from FreeIPMI different than another software?, Why are times reported by FreeIPMI tools wrong?, Top
@section Why is the IPMI kernel driver faster than the KCS driver?

Internally the @acronym{IPMI} kernel driver chooses to spin while
polling for a response from the base management controller
(@acronym{BMC}) while the @acronym{KCS} driver elects to sleep between
poll attempts.  An operating system's scheduler granularity may be
larger than the time it takes to perform a @acronym{IPMI} transaction,
thus the wall clock time of the @acronym{KCS} driver is far worse than
the @acronym{IPMI} kernel driver.  FreeIPMI's @acronym{KCS} driver
implements the sleep between poll attempts because it is believed to
provide better overall system use.  To force the @acronym{KCS} driver
to have similar wall clock response time to the @acronym{IPMI} kernel
driver, users can specify the 'spinpoll' workaround.

@node Why is the output from FreeIPMI different than another software?, Why are there so many IPMI compliance bugs?, Why is the IPMI kernel driver faster than the KCS driver?, Top
@section Why is the output from FreeIPMI different than another software?

Due to minor implementation differences and or incorrect IPMI firmware, the resulting output from FreeIPMI tools can differ from other software.  Here are some of the more common inconsistencies that have been seen before.  More inconsistencies can be seen/fixed by specifying a number of the workarounds available to many of the FreeIPMI tools.

@itemize @bullet

@item
In FreeIPMI's @command{ipmi-sel} and @command{ipmi-sensors} there are options for FreeIPMI to interpret the @acronym{SEL} or sensor readings and give them a NOMINAL, WARNING, or CRITICAL status.  Other IPMI software may have different interpretations for their sensors and/or @acronym{SEL} readings that map to NOMINAL, WARNING, or CRITICAL differently.  These interpretations are configurable in FreeIPMI via the @file{freeipmi_interpret_sel.conf} and @file{freeipmi_interpret_sensor.conf} configuration files.

@item
In some @acronym{IPMI} software, sensor and/or @acronym{FRU} records are bridged by default and read off satellite controllers.  In FreeIPMI they are not due to the discovery that many vendors do not implement their bridging correctly or publish invalid slave addresses in the @acronym{SDR}.  In order to bridge sensors the @option{--bridge-sensors} option must be specified in @command{ipmi-sensors}.  In order to bridge @acronym{FRU} records, the @option{--bridge-fru} must be specified in @command{ipmi-fru}.

@item
In some @acronym{IPMI} software, shared sensors may be read by default.  In FreeIPMI's @command{ipmi-sensors}, they are not read by default due to discovery that too many systems implement this incorrectly.  Shared sensors can be read by specifying the @option{--shared-sensors} option.

@item
In vendor provided @acronym{IPMI} software, @acronym{OEM} specific sensors, @acronym{SEL} records, or FRU records may be output correctly because the vendor is aware of how to properly read/output @acronym{OEM} specific information.  FreeIPMI may not be able to do this by default.  For the motherboards in which @acronym{OEM} information is known, it can be output using the @option{--interpret-oem-data}.  This option is available in @command{ipmi-sensors}, @command{ipmi-sel}, and @command{ipmi-fru}.

@item
In some vendor @acronym{IPMI} software, sensor ``names'' are constructured through a combination of the multiple data in the @acronym{SDR}, rather than just the device name listed in the SDR.  This can lead to different sensor names listed in tools like @command{ipmi-sensors} and @command{ipmi-sel}.  In both tools, this can be alleviated through the use of the @option{--entity-sensor-names} option.

@item
On several HP systems (observed on HP Proliant DL380 G7 and HP ProLiant ML310 G5), the SDR lists sensors using inconsistent information.  Some analog sensors are listed as discrete sensors or vice versa.  This inconsistency, and implementation differences between @command{ipmi-sensors} and other @acronym{IPMI} software lead to different outputs.  For example, this is one such sensor that was seen in @command{ipmi-sensors}:

@example
2  | Power Supply 1  | Power Supply | N/A        | N/A   | 'Presence detected'
@end example

but this same sensor was see in @command{ipmitool} as

@example
Power Supply 1   | 120 Watts         | nc
@end example

In this example, @command{ipmi-sensors} did not output a Watts reading but outputs the proper "Presence Detected" state.  @command{Ipmitool} outputs the correct watts reading, but outputs the invalid non-critical "nc" state.

In FreeIPMI, this problem can be worked around using the 'discretereading' workaround flag.

@item
In FreeIPMI's @command{ipmi-fru}, all multirecord @acronym{FRU} entries are output by default.  In @command{ipmitool} and perhaps other software, they are not.  The resulting output from @command{ipmi-fru} is much larger than other software.  To get similar output in @command{ipmitool}, the @option{-v} option must be set.

@item
In FreeIPMI's @command{ipmi-fru}, @acronym{FRU} record checksums are automatically checked and errors are output if a @acronym{FRU} record cannot assumed to be valid due to a failed checksum check.  Other @acronym{IPMI} software has been shown to ignore the checksums and assume records are valid.  If your system has invalid checksummed @acronym{FRU} entries, the 'skipchecks' workaround can be used to get around them.

@item
In FreeIPMI's @command{ipmi-sensors}, sensors may output an ``OK'' if no events are set.  In other @acronym{IPMI} software (such as @command{ipmitool} and the command ``sdr list''), ``OK'' means that a sensor was simply read correctly.  The ``OK'' may not mean that the device behind the sensor is actually functioning properly.  For example, here is an output from an @command{ipmitool} sdr list entry.

@example
PSU 1 Status     | 0x0b              | ok
@end example

The 0x0b indicates that the power supply has errors (you normally want to see 0x00 or 0x01), however the sensor outputs ``ok'' because the sensor reading was read correctly.  When using FreeIPMI's @command{ipmi-sensors}, the 0x0b is properly converted into the event messages indicating an error.

@example
54  | PSU 1 Status | Power Supply | N/A | N/A | 'Presence detected' 'Power Supply Failure detected' 'Power Supply input lost (AC/DC)'
@end example

@end itemize

@node Why are there so many IPMI compliance bugs?, How do I get around an IPMI compliance bug on my motherboard?, Why is the output from FreeIPMI different than another software?, Top
@section Why are there so many IPMI compliance bugs?

The @acronym{IPMI} specification is very large.  At last check, the
@acronym{IPMI} specification was 601 pages.  This does not count the
various side specifications related to @acronym{IPMI}, including
@acronym{DCMI}, @acronym{PET}, @acronym{FRU}, and the various @acronym{OEM}
extension specifications (e.g. Intel Node Manager).  Many sections of
text can be ambiguous.  Many components of @acronym{IPMI} are optional
and aren't required to be implemented.  There is some leeway for
implementation interpretation as well.  Ultimately, bugs will happen.
In all fairness, FreeIPMI has had bugs too.

A number of the @acronym{IPMI} compliance bugs found by FreeIPMI are documented
in the freeipmi-bugs-issues-and-workarounds.txt document (you can find
it on the website here:
@uref{http://www.gnu.org/software/freeipmi/freeipmi-bugs-issues-and-workarounds.txt}).

@node How do I get around an IPMI compliance bug on my motherboard?, Why am I seeing so many 'internal IPMI error' or 'driver busy' messages?, Why are there so many IPMI compliance bugs?, Top
@section How do I get around an IPMI compliance bug on my motherboard?

Most of the FreeIPMI tools and libraries have flags to workaround a
large number of @acronym{IPMI} compliance bugs found on motherboards.
Please see the appropriate tool manpages or library header files for
details on the workarounds available and for what motherboards.

If you believe there is a compliance issue on your motherboard that
has not yet been implemented, please contact the maintainers on the
@email{freeipmi-devel@@gnu.org} mailing list.

@node Why am I seeing so many 'internal IPMI error' or 'driver busy' messages?, How do I program with the FreeIPMI libraries?, How do I get around an IPMI compliance bug on my motherboard?, Top
@section Why am I seeing so many 'internal IPMI error' or 'driver busy' messages?

In some Linux distributions (atleast with Redhat Enterprise Linux 6.4
/ RHEL 6.4 and CentOS 6.4), the distributions began compiling the IPMI
kernel driver (i.e. ipmi_msghandler and ipmi_si modules) into the
kernel instead of as loadable modules.  This was apparently due to a
need for the IPMI kernel drivers to work with ACPI.

Due to compiling the IPMI kernel driver into the kernel, there is the
potential for inband IPMI communication to occur in the kernel w/o any
knowledge of it from outside software in userspace.  Normally, the
IPMI service (i.e. /etc/init.d/ipmi) is started to create a device
file (i.e. /dev/ipmi0) so that userspace software will know to
communicate through this device.  However, some of these distros
disable the ipmi service so that a device file is never created.

Because of this, multiple IPMI software can communicate inband to the
BMC simultaneously, subsequently racing with each other.  Ultimately,
this can lead to communication problems.  In FreeIPMI, this is most
commonly seen through 'internal IPMI error' or 'driver busy' messages.

There are several possible solutions for this in FreeIPMI.  If you
start the ipmi service (i.e. /etc/init.d/ipmi start), a device file
will be created which FreeIPMI will recognize.  FreeIPMI will
subsequently communicate via inband IPMI through this device file,
thus eliminating racing with the IPMI occurring in the kernel.

The other option is to disable the IPMI kernel thread so that FreeIPMI
can perform inband communication with the BMC through its own
mechanisms.  The following is from the Linux kernel documentation.

@example
When compiled into the kernel, the parameters can be specified on the
kernel command line as:

  ipmi_si.type=<type1>,<type2>...
       ipmi_si.ports=<port1>,<port2>... ipmi_si.addrs=<addr1>,<addr2>...
       ipmi_si.irqs=<irq1>,<irq2>... ipmi_si.trydefaults=[0|1]
       ipmi_si.regspacings=<sp1>,<sp2>,...
       ipmi_si.regsizes=<size1>,<size2>,...
       ipmi_si.regshifts=<shift1>,<shift2>,...
       ipmi_si.slave_addrs=<addr1>,<addr2>,...
       ipmi_si.force_kipmid=<enable1>,<enable2>,...
       ipmi_si.kipmid_max_busy_us=<ustime1>,<ustime2>,...

...

If your IPMI interface does not support interrupts and is a KCS or
SMIC interface, the IPMI driver will start a kernel thread for the
interface to help speed things up.  This is a low-priority kernel
thread that constantly polls the IPMI driver while an IPMI operation
is in progress.  The force_kipmid module parameter will all the user to
force this thread on or off.  If you force it off and don't have
interrupts, the driver will run VERY slowly.
@end example

@node How do I program with the FreeIPMI libraries?, Where can I get additional help or support?, Why am I seeing so many 'internal IPMI error' or 'driver busy' messages?, Top
@section How do I program with the FreeIPMI libraries?

If you are looking for a high level library to do Serial-over-LAN
(@acronym{SOL}) or @acronym{IPMI} sensor/@acronym{SEL} monitoring, you
may wish to look at the libipmiconsole and libipmimonitoring
libraries.  These libraries attempt to abstract a large amount of the
underlying @acronym{IPMI} detail from developers.  The majority of the
documentation can be found in the header files.  Some examples can be
found in the documentation and the FreeIPMI tools that use them.

The libfreeipmi library is the core library used by other FreeIPMI
libraries and tools.  However, it is quite detailed in regards to the
@acronym{IPMI} specification and many components of the library will
be quite confusing to those unfamiliar with the finer details of the
@acronym{IPMI} specification.  It is recommended most use the higher
level libraries described above.

A more detailed description of the available FreeIPMI libraries can be
found in the @file{freeipmi-libraries.txt} document (you can find it
on the website here:
@uref{http://www.gnu.org/software/freeipmi/freeipmi-libraries.txt}).

@node Where can I get additional help or support?, , How do I program with the FreeIPMI libraries?, Top
@section Where can I get additional help or support?

For help, please email the @email{freeipmi-users@@gnu.org} mailing list.

@bye
