IPMI Java Client

This project is a fork of the excellent IPMI Library for Java by Verax Systems (see also). It is however not related to another fork by rbuckland.

See Project Documentation and the Javadoc for more information on how to use this library in your code.

The IPMI Java Client talks to the Baseboard Management Controller (BMC) of a server over IPMI 2.0 over LAN (RMCP+): it identifies the BMC (manufacturer, product, firmware revision), reads the chassis status, the Field Replaceable Units (FRUs), the sensors of the SDR repository and the System Event Log (SEL) as typed Java objects, controls the power and the identify LED, opens Serial over LAN consoles, and sends any IPMI command in the same session. It requires Java 8 or later and has no dependency.

try (IpmiClient bmc = IpmiClient.builder("bmc.example.com").credentials("monitor", password).build()) {
    ChassisStatus chassis = bmc.chassisStatus();
    System.out.println("Power is " + (chassis.powerOn() ? "on" : "off"));

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

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

    for (SelEntry entry : bmc.sel().execute()) {
        System.out.println(entry.timestamp() + " " + entry.sensorType() + " " + entry.description() + " " + entry.direction());
    }
}

A client owns one RMCP+ session, opened by the first operation and closed by close(): always use it in a try-with-resources block. The BMC must have IPMI over LAN enabled and an account with the User privilege, Operator on most BMCs for the sensors and FRUs of other controllers than the BMC (power supplies, fans, RAID adapter...), which the BMC reaches with Send Message: see Preparing the BMC. privilege(PrivilegeLevel.MaximumAvailable) runs the session at User and raises it only when a command needs more, as far as the account allows (Raising the session on demand).

Command-line client

The library comes with a command-line client, ipmicli, that exposes the same operations. Install it with one command (Java 8 or later required):

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

On Windows (PowerShell):

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

See the installation page for details. The client is a self-contained executable jar (target/ipmi-java-<version>-standalone.jar, also on the releases page), which java -jar runs as well.

What the BMC offers, before any login:

ipmicli -h bmc.example.com probe

The sensors, with the password read from a file:

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

The FRU inventory as JSON Lines:

ipmicli -h bmc.example.com -u monitor -pf password.txt fru --json

Subcommands: probe, info (the identity of the BMC), chassis, power status|on|off|cycle|reset|soft|diag, identify, sensors, fru, sel (the System Event Log, --since <id> for the new entries), sol (an interactive Serial over LAN console) and raw (any request, like ipmitool raw: raw 0x2c 0x01 0xdc 0x01). Diagnostics go to stderr, the exit code says what failed (77 authentication, 69 unreachable, 124 timeout...). See the Command-Line Client page for the options, the output formats and the ipmitool equivalents.

Upgrading

Version 2.0.00 replaces the client API of 1.x and removes the SLF4J dependency; see Upgrading from 1.x for the migration table.

• IpmiClientConfiguration and the static methods of IpmiClient are replaced by the builder above: IpmiClient.builder(host).credentials(user, password).build() returns a reusable, thread-safe, AutoCloseable client that keeps one session open across its operations (deviceId(), chassisStatus(), chassisControl(PowerCommand), chassisIdentify(seconds), sensors(), frus(), sel(), send(command), raw(netFn, command), sol().open(), capabilities()), walks the SDR repository once for frus() and sensors(), and reopens the session when the BMC loses it. The cipher suite preference, the privilege level, the message timeout, the retries and the keep-alive period are settings of the builder; PropertiesManager and the connection.properties and vxipmi.properties files are removed.
• The results are typed and immutable (ChassisStatus, Sensor with its converted reading, thresholds, status and states, Fru with its decoded areas, SelEntry with its sensor, event, direction and timestamp, SensorList and FruList with the SDR records the walk skipped), and replace the org.metricshub.ipmi.client.model classes. The semicolon-separated text output (IpmiResultConverter, DeviceDescription) is MetricsHub's format and moves to the MetricsHub IPMI extension, where it stays byte for byte the same.
• The checked ExecutionException, TimeoutException and InterruptedException are replaced by the unchecked IpmiClientException hierarchy: IpmiAuthenticationException, IpmiConnectionException, IpmiTimeoutException, IpmiCompletionCodeException.
• The library no longer logs: the problems that do not fail an operation are reported in its result (Sensor.problem(), Fru.problems(), skippedRecords(), ReadFruData.decodeFruData(data, problems)), and org.slf4j:slf4j-api is no longer a dependency.
• In the low-level API, the commands no longer take IpmiVersion, CipherSuite and AuthenticationType in their constructors (the session sets them when it sends the command), IpmiCommandCoder<R> declares the response type so that IpmiConnector.sendMessage() returns it without a cast, IpmiConnector.setTimeout(int) and setRetries(int) replace the properties files, CipherSuite.forId(id) builds a standard suite, IpmiCommandCoder.getNetworkFunctionCode() and IpmiLanRequest(int networkFunctionCode, ...) write commands of the extension and OEM network functions (DCMI), and a wrong password fails the handshake with AuthenticationException.

Build instructions

This is a simple Maven project. Build with:

mvn verify

mvn verify site also builds the documentation in target/site (sources in src/site).

Code format

The code is formatted with the MetricsHub Eclipse formatter profile (metricshub-eclipse-formatter.xml, shared with the other MetricsHub Java projects), and the build fails on unformatted code. Simply run the below command before committing:

mvn formatter:format

The build also fails on Checkstyle violations. A justified violation can be suppressed with // CHECKSTYLE.OFF: <RuleName> and // CHECKSTYLE.ON: <RuleName> comments.

The build fails on any SpotBugs bug as well. An intentional one is suppressed with @SuppressFBWarnings and a justification.

To ignore the whole-tree reformat commit in git blame, run once:

git config blame.ignoreRevsFile .git-blame-ignore-revs

Release instructions

The artifact is published to Maven Central through the Central Portal with the central-publishing-maven-plugin (server Id central, authenticated with a Portal user token). Manual deployments require these credentials in your Maven settings.xml.

It is strongly recommended to only use GitHub Actions "Release to Maven Central" to perform a release:

• Manually trigger the "Release to Maven Central" workflow
• Specify the version being released and the next version number (SNAPSHOT)
• The workflow creates the GitHub release, then adds the ipmi-java-standalone.jar alias and the .sha256 checksums that the ipmicli installers download (if that last job fails, re-run it: the installers fail until it succeeds)
• Publish the pending deployment on the Central Portal (the workflow uploads and validates it, but does not publish it automatically)
• Merge the PR that has been created to prepare the next version

License

License is GNU General Lesser Public License (LGPL) version 3.0. The IPMI Library for Java by Verax Systems is published under the GNU GPL v3; this fork uses it under a commercial (non-GPL) license granted by Verax Systems to Sentry Software in 2021. The source files derived from it keep Verax Systems as copyright holder.

Each source file includes the LGPL-3 header (build will fail otherwise). To add the header to new source files, simply execute the below command (existing headers are never modified):

mvn license:update-file-header