FreeIPMI - Copyright (C) 2003-2015 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.

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 userspace KCS
interface driver, a SSIF driver through the Linux SSIF device
(i.e. /dev/i2c-0), the OpenIPMI Linux kernel driver (i.e. /dev/ipmi0),
the Sun/Solaris BMC driver (i.e. /dev/bmc), and the Intel DCMI/MEI
driver (i.e. /dev/dcmi).  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 ipmi-config(8).
Additional information on how to configure with ipmi-config(8) can be
found in the ipmi-config.conf(5) manpage.  Some vendors may
pre-configure their motherboards with default values so that
ipmi-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 workaround
must be specified into FreeIPMI to ensure the tool can execute
properly.  For example, a fair number of vendors have populated their
FRU records with invalid checksums.  To properly ignore these set of
checksums a 'skipchecks' workaround has been added to ipmi-fru(8).
Please see each of the tool manpages to see a list of available
workarounds.

Additional information, examples, and general trouble-shooting can be
found in each of the tool manpages.

General Use
-----------

The primary tools that most users of FreeIPMI will be interested in
for system management are the following:

ipmi-sensors

A tool to read IPMI sensor readings to aid in system monitoring.

ipmi-sel

A tool to read and manage IPMI System Event Log (SEL) records to aid
in system debugging.

ipmipower

A tool for remote power control.

ipmiconsole

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

Many other tools and libraries are listed below that cover additional
features and areas of IPMI.

Additional information, examples, and general trouble-shooting can be
found in each of the tool manpages.

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

In order to avoid typing in a long list of command line options to
specify IPMI communication requirements every time a command is
executed (e.g. 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.  Ipmi-config(8)
comes 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.
Ipmi-sensors(8) and the libipmimonitoring(3) library support the
ability to interpret 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.

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

The following tools are distributed and supported by FreeIPMI.

bmc-info

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

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-config

A tool to configure BMC and IPMI information.  In can be used to
configured usernames, passwords, networking information, security,
Serial-over-LAN (SOL), Platform Event Filtering (PEF), boot devices,
power restoration policy, sensor thresholds, sensor events, and many
more configuration options.

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.

ipmi-pet

A tool to parse and interpret Platform Event Traps (PET).

ipmi-dcmi

A tool to perform Data Center Manageability Interface (DCMI) IPMI
extension commands.  Supports extensions for asset management and
power usage management.

bmc-device

A tool to perform advanced BMC commands, such as resetting the BMC,
configuring ACPI, configuring SDR/SEL time, manually generating
events, re-arming sensors, and configuring manufacturer settings.

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.

ipmiseld

A daemon that regularly polls the SEL and stores the events to the
local syslog.

Additional information, examples, and general trouble-shooting can be
found in each of the tool manpages.

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

The following libraries are distributed and supported by FreeIPMI.

libfreeipmi

A C library that includes KCS, SSIF, OpenIPMI Linux, and Solaris BMC
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.  This library is for programmers
intimately familiar with the IPMI protocol and IPMI specification.
Most users may wish to use the libraries listed below.

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 and system event log (SEL) monitoring that
abstracts away most IPMI details.  Interpretation of those sensors and
events is abstracted into an API with an iterator interface.

libipmidetect

A library for IPMI node detection.

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

Local FreeIPMI argp modified from argp-standalone-1.3.  Many
configure.ac autoconfing for the local argp library taken from
argp-standalone as well.

argp-standalone taken from glibc from Neil Moller.
http://www.lysator.liu.se/~nisse/misc/

Building/Install from source
----------------------------

The instructions below (modified from the INSTALL file) should
work for most people.

  1. `cd' to the directory containing the package's source code and type
     `./configure' to configure the package for your system.

     Running `configure' takes awhile.  While running, it prints some
     messages telling which features it is checking for.  If your system
     requires additional packages and/or libraries in order for FreeIPMI
     to be built, appropriate messages should be displayed.  These
     packages and/or libraries should be installed and `./configure' should
     be executed again.

  2. Once `./configure' has succeeded, type `make' to compile the
     package.

  3. Type `make install' to install the programs and any data files and
     documentation.

     You may need to be root in order for files to be installed into
     the proper locations on your system.

By default files will typically be installed in /usr/local (binaries
in /usr/local/bin, libraries in /usr/local/lib, configuration files in
/usr/local/etc/, etc.).  To install into the more common locations
such as /usr/bin, /usr/lib/, /etc, etc. the options passed into
`./configure' must be adjusted.

The following set of options and settings are suitable for most Linux
systems.

--prefix=/usr --exec-prefix=/usr --sysconfdir=/etc
--localstatedir=/var --mandir=/usr/share/man

Your mileage may vary depending on your system.

If you install the binaries or libraries in non-standard locations
(e.g. /usr/local or /opt), you may have to update other system
configuration to find the files and libraries.  For example, in Linux
you may need to update your PATH or LD_LIBRARY_PATH environment
variables.  Or you may need to update your /etc/ld.so.conf files and
run ldconfig(8) to find libraries globally.  This is highly dependent
on your operating system.

Building RPMs
-------------

For most people you can build RPMs one of two ways.

From the source:

rpmbuild -ta freeipmi-X.Y.Z.tar.gz

From the source rpm:

rpmbuild --rebuild freeipmi-X.Y.Z-1.src.rpm

Depending on your default RPM build environment, you may need to be root
in order for RPMs to be stored in the default locations.

After the RPMs are built, you may install them the normal way:

rpm -i freeipmi-X.Y.Z.ARCH.rpm

Additional configure options
----------------------------

The following configure options are available to users for more unique
compilation requirements and environments.

--without-encryption

This option disables compilation of encryption support in FreeIPMI.
Most notably, this disables encryption support when doing out of band
IPMI 2.0 communication.

This option may be particularly useful in embedded environments that
do not have the libraries needed to compile encryption support.

--with-dont-check-for-root

When running tools inband, root access is normally required.  In some
systems, this may not be desired.  This options removes the check for
root access in FreeIPMI tools.

--without-random-device

This option disables checks and use of /dev/urandom and /dev/random.
This may be required for embededded systems without these devices.

--with-pkgconfig-dir

This option can configure an alternate default pkgconfig directory.

--with-bmc-watchdog-logfile

This option can configure an alternate default bmc-watchdog log
directory.

--with-ipmi-monitoring-sdr-cache-dir

This option can configure an alternate default libipmimonitoring SDR
cache directory.

The Linux OpenIPMI driver is often loaded via the /etc/init.d/ipmi
setup script.  If your distribution/environment does not have this
script, the following script can be used to load/unload the driver.

#!/bin/sh

/sbin/modprobe ipmi_devintf

maj=`cat /proc/devices | awk '/ipmidev/{print $1}'`
if [ -c /dev/ipmi0 ]
then
   rm -f /dev/ipmi0
   /bin/mknod /dev/ipmi0 c $maj 0
else
   /bin/mknod /dev/ipmi0 c $maj 0
fi

/sbin/modprobe ipmi_si

# do stuff

/sbin/rmmod ipmi_si
/sbin/rmmod ipmi_devintf
/sbin/rmmod ipmi_msghandler