Overview

The IPMI Java Client talks to the Baseboard Management Controller (BMC) of a server (Dell iDRAC, HPE iLO, Lenovo XClarity Controller (XCC) and ThinkServer System Manager (TSM), Cisco IMC, Fujitsu iRMC, Supermicro, and the BMC firmwares of most other boards; see Tested BMCs^[1]) over IPMI 2.0 (Intelligent Platform Management Interface) over LAN, in the authenticated RMCP+ (Remote Management Control Protocol) sessions of IPMI 2.0, on UDP port 623. It lets a Java application:

• identify the BMC: manufacturer and product IDs, firmware revision, IPMI version and the functions it provides (Device ID^[2]),
• probe the BMC before any login, without credentials: the cipher suites it offers and its login options (What the BMC supports before the login^[3], BmcCapabilities^[4]),
• read the chassis status: power on or off, last power event, power restore policy, faults, intrusion, and control the power (on, off, cycle, reset, soft shutdown, diagnostic interrupt) and the identify LED (Chassis Status^[5]),
• read the FRU inventory: manufacturer, product name, part and serial numbers of the chassis, boards, power supplies and other Field Replaceable Units, the Serial Presence Detect (SPD) data of memory modules and the Processor Information ROM of Intel Xeon processors (FRU Inventory^[6]),
• read the sensors that the Sensor Data Records (SDRs) of the BMC describe (Full and Compact sensor records), including those of the other controllers of the server (power supplies, fans, RAID adapters), which the BMC reaches with Send Message: temperatures, voltages, fan speeds, currents, power and energy readings with their thresholds, and the discrete states (presence, redundancy, failure, …); Sensors^[7] lists what is not read,
• read the System Event Log: the hardware events the BMC logged (thresholds crossed, power supply failures, memory errors, intrusion), whole or since the last entry read (System Event Log^[8]),
• open a Serial over LAN console on the server's serial port (Serial over LAN^[9]), and
• send any IPMI command in the same session, as a command class or as raw bytes, or through the low-level connector (Low-Level API^[10]), including the commands of the Data Center Manageability Interface (DCMI) and of the OEM network functions.

deviceId(), capabilities(), chassisStatus(), frus(), sensors() and sel() only read: besides the session commands, they send Get commands, Read FRU Data, the Reserve commands that some BMCs require before the SDR repository or the SEL is read, and Send Message to reach the other controllers (Supported Commands^[11]); they change nothing on the server. The power control, the identify LED and the Serial over LAN console act on the server or the BMC, and so can the commands sent with send() or raw().

The same operations are available from the command line with the ipmicli client (Command-Line Client^[12]). Install it with one command (Installation^[13] has the details):

curl -fsSL https://metricshub.org/ipmi-java/get | sh

irm https://metricshub.org/ipmi-java/get.ps1 | iex

Then, for example, list the sensors of a BMC:

ipmicli -h bmc.example.com -u monitor -pf pw.txt sensors

The library is the IPMI engine of MetricsHub^[14] hardware monitoring: its IpmiClient^[15] returns the identity of the BMC, the chassis status, the inventory, the sensors and the System Event Log as typed Java objects.

It is a fork of the IPMI Library for Java by Verax Systems^[16], with the RAKP-HMAC-SHA256 and RAKP-HMAC-MD5 authentication and the HMAC-SHA256-128, HMAC-MD5-128 and MD5-128 integrity algorithms added (cipher suites 6 to 8, 11, 12 and 15 to 17), tolerance for the OEM records that vendors put in their SDR repository, and many fixes. Moving from the Verax library takes a package rename and a few code changes (Migrating from Verax^[17]).

The library is free software, published under the GNU Lesser General Public License v3.0^[18]: applications under any license can use it, and a modified version of the library that you distribute stays under the LGPL.

Add the dependency

The library requires Java 8 or later, has no dependency, and is published on Maven Central^[19]:

<dependency>
  <groupId>org.metricshub</groupId>
  <artifactId>ipmi-java</artifactId>
  <version>2.2.01</version>
</dependency>

See Installation^[20] for Gradle and the requirements.

Quick start

Everything starts with IpmiClient.builder(host), which returns an IpmiClient.Builder^[23]: the client it builds owns one session with the BMC, opened by the first operation and closed by close(), so always use it in a try-with-resources block.

import org.metricshub.ipmi.client.ChassisStatus;
import org.metricshub.ipmi.client.Fru;
import org.metricshub.ipmi.client.IpmiClient;
import org.metricshub.ipmi.client.Sensor;

public class Example {

	public static void main(String[] args) {
		try (IpmiClient bmc = IpmiClient
				.builder("bmc.example.com")                 // host name or IP address of the BMC
				.credentials("monitor", "the-password".toCharArray())
				.build()) {

			ChassisStatus chassis = bmc.chassisStatus();
			System.out.println("Power is " + (chassis.powerOn() ? "on" : "off"));

			for (Fru fru : bmc.frus().execute()) {
				System.out.println(fru.name() + ": " + fru.manufacturer() + " " + fru.model() + " S/N " + fru.serialNumber());
			}

			for (Sensor sensor : bmc.sensors().execute()) {
				sensor.reading().ifPresent(value ->
						System.out.println(sensor.name() + " = " + value + " " + sensor.unit() + " (" + sensor.status() + ")"));
			}
		}
	}
}

Which prints, on a Lenovo RD350 (an excerpt: the server has 49 sensors and more FRUs; serial numbers masked):

Power is on
MotherBoard FRU: LENOVO RD350 S/N S4M00000
PSU1 FRU: LITEON PS-2451-6L-LF S/N 0000
Ambient Temp = 19.0 DegreesC (OK)
System Power = 88.0 Watts (OK)
Fan 1 = 6600.0 Rpm (OK)
System 3.3V = 3.38 Volts (OK)

The client runs its operations one at a time on its session, walks the SDR repository once for both frus() and sensors() while the repository does not change (SDR cache^[24]), and reopens the session when the BMC loses it.

Every failure of an operation, except a call the API does not allow (below), is an unchecked IpmiClientException^[25], whose subclass says what to act on (Timeouts and Errors^[26]):

try (IpmiClient bmc = IpmiClient.builder(host).credentials(user, password).build()) {
	ChassisStatus chassis = bmc.chassisStatus();
	// ...
} catch (IpmiAuthenticationException e) {
	// the BMC refused the login: user name, password, BMC key or privilege level
} catch (IpmiConnectionException e) {
	// no session: unknown host, UDP port 623 filtered, IPMI over LAN disabled
} catch (IpmiTimeoutException e) {
	// a message got no reply, or the operation outlived its deadline
} catch (IpmiCompletionCodeException e) {
	// the BMC refused a command: e.completionCode() says why (D4h: insufficient privilege)
} catch (IpmiClientException e) {
	// any other failure: no cipher suite in common, a BMC without IPMI 2.0, a malformed reply
}

A call the API does not allow throws a standard Java exception instead: an invalid setting or argument, of the builder or of an operation (chassisIdentify(300)), throws IllegalArgumentException before anything is sent to the BMC, and any operation of a closed client, an operation that needs a session on a client built without credentials, or a power cycle of a system that is off throws IllegalStateException (Invalid settings and calls^[27]).

Where to go next

• Installation^[20] — coordinates, supported JDKs and requirements, the one-command installation of ipmicli
• Command-Line Client^[12] — ipmicli: the identity of the BMC, the chassis status, the power control, the sensors, the FRUs, the System Event Log and a Serial over LAN console from the command line
• Preparing the BMC^[22] — the tested BMCs, enabling IPMI over LAN, the account, privilege level and cipher suites, the firewall
• Device ID^[2] — manufacturer, product and firmware revision of the BMC, the functions it provides, and what it supports before any login: cipher suites and login options (capabilities())
• Chassis Status^[5] — power state and chassis flags, power control, identify LED
• FRU Inventory^[6] — how FRUs are read, which fields are reported, memory modules and processors
• Sensors^[28] — readings, thresholds, status and states, sensor owners and shared records
• System Event Log^[8] — the logged events, OEM entries, polling for new entries
• Serial over LAN^[9] — a console on the server's serial port
• Configuration^[29] — every option of the client builder
• Timeouts and Errors^[30] — deadlines, message timeouts, retries, session recovery and the exceptions
• Low-Level API^[10] — IpmiConnector: sessions, cipher suites, any IPMI command
• Supported Commands^[31] — commands, cipher suites, SDR, SEL and FRU records, and the specifications whose sections and tables the site cites (References^[32])
• Troubleshooting^[33] — common failures and how to diagnose them with ipmitool or ipmiutil
• Upgrading^[34] — changes between versions, and the migration from 1.x
• Migrating from Verax^[17] — moving from the Verax IPMI Library for Java
• Javadoc^[35] — the API reference