FreeIPMI - Copyright (C) 2003-2008 FreeIPMI Core Team

FreeIPMI
--------

FreeIPMI provides in-band and out-of-band IPMI software based on the
IPMI v1.5/2.0 specification.

What is IPMI?
-------------

The IPMI specification defines a set of interfaces for platform
management.  It is utilized by a wide variety of vendors for system
management on motherboards.  The features of IPMI that most users will
be interested in are sensor monitoring, remote power control,
serial-over-LAN (SOL), and system debugging.  The FreeIPMI tools and
libraries listed below should provide users with the ability to access
and utilize these features.

Project Tools
-------------

Bmc-info

A tool to read information about a BMC such as device version numbers,
device support, and global IDs (guids).

Bmc-config

A tool to configure general BMC and IPMI information.  Supports
configuration of usernames, passwords, networking information,
security, Serial-over-LAN (SOL), and other core fields.

Bmc-watchdog

A tool/daemon to manage a BMC Watchdog. This tool is typically used
for system timeout management and automatic system restarts in the
event of a system crash.  

Ipmi-chassis

A tool to manage/monitor a chassis, such as chassis power,
identification (i.e. LED control), and status.

Ipmi-fru

A tool to read field replaceable unit (FRU) information from a
motherboard/machine.

Ipmi-sel

A tool to read and manage IPMI System Event Log (SEL) records.  SEL
records store system event information and may be useful for debugging
problems.

Ipmi-sensors

A tool to read IPMI sensor readings and sensor data repository (SDR)
information.

Ipmipower

A tool for remote power control.

Ipmiconsole

A tool for Serial-over-Lan (SOL) console access.

Ipmi-raw

A tool that provides hex input/output of IPMI commands.

Ipmi-locate

A tool that can probe for information about the location of a BMC
device, such as device addresses.

Ipmimonitoring

A tool for sensor monitoring and interpretation.  The tool is similar
to ipmi-sensors, but sensor readings are analyzed and mapped into
Nominal, Warning, and Critical states.

Pef-config

A tool to configure Platform Event Filtering (PEF) information.

Ipmi-chassis-config

A tool to configure IPMI chassis information.  Supports configuration
of boot device, power restore policy, and other chassis related
fields.

Ipmi-sensors-config

A tool to configure IPMI sensors.  Supports configuration of sensor
thresholds, sensor events, and other sensor related fields.

Bmc-device

A tool to perform advanced BMC commands.

Ipmiping

An IPMI ping tool for debugging. 

Rmcpping

A RMCP ping tool for debugging. 

Ipmi-oem

An IPMI tool for OEM specific commands.

Ipmidetect/Ipmidetectd

A tool and daemon for IPMI node detection.

Project Libraries
-----------------

Libfreeipmi

A C library that includes KCS, SSIF, and OpenIPMI drivers, IPMI
1.5 and IPMI 2.0 LAN communication interfaces, IPMI packet building
utilities, IPMI command utilities, and utilities for
reading/interpreting/managing IPMI.

Libipmiconsole

A library for Serial-over-Lan (SOL) console access.  SOL console
access is abstracted into a file descriptor interface, so users may
read and write console data through a file descriptor.

Libipmimonitoring

A library for sensor monitoring and interpretation.  Sensor monitoring
and interpretation of those sensors is abstracted into an API with
an iterator interface.

Libipmidetect

A library for IPMI node detection.

Getting Started with IPMI
-------------------------

IPMI can be used in-band (i.e. running on a machine locally) or
out-of-band (i.e. connecting remotely).

Most FreeIPMI tools can operate in-band by using one of the in-band
drivers included.  These in-band drivers include a direct KCS
interface driver, a Linux SSIF driver through the SSIF device
(i.e. /dev/i2c-0), the OpenIPMI Linux kernel driver (i.e. /dev/ipmi0),
and the Sun/Solaris BMC driver (i.e. /dev/bmc).  If your system
requires the use of installed drivers, those appropriate modules must
be installed ahead of time.  However, most systems should
automatically load these drivers when appropriate.

Under most scenarios, the FreeIPMI tools should automatically discover
which in-band interface to use and the proper settings to use.  Users
may execute the tools on the command line to begin using them.  Some
motherboards may require you to determine driver type, addresses,
paths, etc. on your own and pass them as command line options to the
tools.  You may use ipmi-locate(8) to help determine this information.
Other tools such as dmidecode(8) may also provide this information.

To use IPMI out-of-band with tools such as ipmipower(8) or
ipmi-sensors(8), the remote machine's BMC must first be configured for
out of band communication.  Typically, this involves setting a
username, password, IP address, MAC address, and a few other
parameters.  This can be done using the tool bmc-config(8).
Additional information on how to configure with bmc-config(8) can be
found in the bmc-config.conf(5) manpage.  Some vendors may
pre-configure their motherboards with default values so that
bmc-config(8) can be used remotely to configure the machine.  However,
most of the time, the BMC must be configured in-band before
out-of-band access can be allowed (for example, the correct IP address
and MAC address must be configured).

In order to remotely connect to a machine, you typically must specify
the host, username, and password for the tool in order to connect.
Depending on configuration settings, a K_g key, privilege level,
authentication type, cipher suite id, or protocol version may need to
be specified.  Some vendors may have not implemented IPMI properly and
a vendor specific workaround may also be necessary.  See tool manpages
for more information and general trouble-shooting information.

Configuration
-------------

In order to avoid typing in a long list of command line options to
specify IPMI communication requirements everytime a command is
executed (i.e. driver paths, usernames, passwords, etc.), an
alternate set of default values can be set for most FreeIPMI
tools in the FreeIPMI configuration file.  See freeipmi.conf(5)
for more information.

HPC Support
-----------

Much of FreeIPMI was written with HPC support in mind.  The
configuration tools (bmc-config(8), pef-config(8),
ipmi-sensors-config(8), and ipmi-chassis-config(8), come with file
input/output support so that configuration can be copied and verified
across nodes in a cluster.  Most tools (like ipmipower(8) and
ipmi-sensors(8)) come with hostrange support so multiple hosts can be
specified on the command line at the same time and IPMI can be
executed against the hosts in parallel.  See tool manpages for more
information.  Also see the document freeipmi-hostrange.txt for
detailed usage and explanation.  The ipmimonitoring(8) tool interprets
sensor readings as well as just reporting them.  By mapping sensor
readings into NOMINAL, WARNING, or CRITICAL states, it makes
monitoring sensors easier across large numbers of nodes.

Development
-----------

For information on the libraries that can be used to program IPMI
applications with, please see, please see libfreeipmi(3),
libipmiconsole(3), libipmimonitoring(3), and libipmidetect(3).  Or
see the document freeipmi-libraries.txt.

Help, Questions, etc.
---------------------

Please send comments, help, and questions to the freeipmi mailing
lists, freeipmi-users@gnu.org and freeipmi-devel@gnu.org.  Or see
our webpage at http://www.gnu.org/software/freeipmi/.