Low-Level API

Reading the System Event Log

sel()^[11] reads the log; the raw commands behind it are Get SEL Info and one Get SEL Entry per entry, following the next record IDs:

GetSelInfoResponseData info = bmc.send(new GetSelInfo());
System.out.println("SEL entries: " + info.getEntriesCount());

if (info.getEntriesCount() > 0) { // Get SEL Entry fails on an empty SEL
	// A whole entry needs no reservation (IPMI 2.0, section 31.5): reservation ID 0
	int recordId = 0; // 0: the first entry
	while (recordId != 0xFFFF) { // 0xFFFF: no more entries
		GetSelEntryResponseData entry = bmc.send(new GetSelEntry(0, recordId));
		SelRecord record = entry.getSelRecord();
		System.out.println(record.getRecordId() + " " + record.getRecordType() + " " + record.getTimestamp() + " "
				+ record.getSensorType() + " " + record.getEvent() + " " + record.getEventDirection());
		recordId = entry.getNextRecordId();
	}
}

SEL entries: 643
1 System Wed May 15 11:15:25 CEST 2024 EventLoggingDisabled LogAreaReset Assertion
2 OemTimestamped Wed May 15 11:16:11 CEST 2024 null null null
5 System Wed May 15 11:23:27 CEST 2024 PowerUnit PowerOffOrDown Assertion
6 System Wed May 15 11:23:34 CEST 2024 PowerUnit PowerOffOrDown Deassertion

SelRecord keeps the timestamp as the BMC sent it (a Date of the unsigned 32-bit value, so FFFFFFFFh and the pre-init values are dates of 2106 and of 1970 to 1987); SelEntry of the client tells them apart (Timestamps^[12]).

Controlling the power

chassisControl()^[13] wraps the Chassis Control command, and chassisIdentify() the Chassis Identify command. The coders can also be sent yourself, on a client built with the Operator or Administrator privilege^[14], but send() has none of the safeguards of the operations: it sends the command again after a lost reply or a C3h, with the configured retries^[15], so a reset or a power cycle can reach the BMC twice, and it does not refuse a PowerCycle of a system that is off. Prefer the operations for the power commands; send() is for the commands the client does not wrap:

bmc.send(new ChassisControl(PowerCommand.PowerUp)); // chassisControl(PowerCommand.PowerUp) is safer
bmc.send(new ChassisIdentify(15, false)); // 15 seconds; (0, false) turns it off, (0, true) forces it on

PowerCommand has the six controls of the specification: PowerUp, PowerDown (immediate, without shutting down the operating system), PowerCycle, HardReset, SoftShutdown and DiagnosticInterrupt.

Raw requests

raw()^[16] sends any request as bytes, like ipmitool raw, and returns its reply whatever its completion code: a RawResponse^[17] with completionCode(), rawCompletionCode() and data(), the response data after the completion code. Get DCMI Capabilities Info, under the Group Extension network function (2Ch), whose first data byte is the defining body (DCh for DCMI), with the parameter 01h:

RawResponse dcmi = bmc.raw(0x2C, 0x01).data(0xDC, 0x01).execute();
System.out.println(dcmi);
if (dcmi.completionCode() == CompletionCode.Ok) {
	byte[] data = dcmi.data(); // DCh, then the DCMI version: 01h 05h is DCMI 1.5
}

completion code 00h, data DC 01 05 02 00 01 07

Any request network function is accepted, 00h to 3Eh: the standard ones, Transport (0Ch), Group Extension (2Ch), OEM/Group (2Eh, whose first three data bytes are an IANA enterprise number) and the controller-specific OEM ones (30h to 3Eh). The odd codes are those of the responses (IPMI 2.0, section 5.1) and fail with IllegalArgumentException, like a command or a data byte out of the 0-255 range. An error completion code is returned, not thrown, and not retried, a busy one (C0h) or a C3h included. Like send(), the request is sent again when its reply is lost and never replayed on a new session, and it has none of the safeguards of the power operations. It runs at the privilege level of the session: a request that needs Operator gets D4h from a client built at User.

Choosing the cipher suite

getAvailableCipherSuites() returns the standard suites the BMC offers, in the BMC's order, with the algorithms of the table^[21] (the OEM suites are left out), including suites the library does not implement. Choose one it implements, with integrity: 3 or 17 in practice; CipherSuite.isSupported() tells whether the library implements the algorithms of a suite, and a suite with an xRC4 or MD5-128 algorithm fails when the session is opened. Do not fall back to a suite without integrity (0, 1, 6, 15) just because the BMC lists nothing else: the list is not authenticated. To skip the discovery when you already know the suite, build it with CipherSuite.forId() and pass it to createConnection() (Get Channel Authentication Capabilities is not sent either: an IPMI 1.5-only BMC then just does not answer):

// Suite 17: RAKP-HMAC-SHA256, HMAC-SHA256-128, AES-CBC-128
ConnectionHandle handle = connector.createConnection(address, 623, CipherSuite.forId(17), PrivilegeLevel.User);
connector.openSession(handle, "monitor", "the-password", null);

Privilege level

The PrivilegeLevel^[22] requested in getChannelAuthenticationCapabilities() (or createConnection()) is the maximum level of the session: User for reading, Operator for most control commands (chassis control, setting the boot device), Administrator for configuration commands and Serial over LAN. Every session starts at the User level whatever that maximum (IPMI 2.0, section 22.18), so for Operator and Administrator, openSession() raises it with SetSessionPrivilegeLevel^[23] right after the handshake, as IpmiClient and ipmitool do: the session it returns runs at the requested level.

An account (or a cipher suite) limited to a lower level may still log in, the BMC capping the session at its limit, but it refuses the raise: 80h (the level is not available for this user), 81h (it exceeds the privilege limit of the channel or of the user), or another completion code. openSession() then closes the session and throws SessionException, whose cause is the IPMIException of the completion code: request the level the commands need. A User session is not raised, nor one requested with MaximumAvailable, which names no level: send SetSessionPrivilegeLevel yourself for the latter.

Timeouts

setTimeout(ms) sets the message timeout^[15] of the connections created afterwards, setTimeout(handle, ms) that of one connection. Call them before createConnection() or right after: the timeout then also applies to the handshake. sendMessage() retries a message getRetries() times (3 by default) before throwing. Unlike IpmiClient, the connector has no overall deadline: bound it yourself if you need one.

Writing your own command

A command the library does not implement is a subclass of IpmiCommandCoder<R>^[9], where R is the type of its response: return its network function and command code, build the request data in preparePayload(), and decode the response in getResponseData(), where validateResponse() checks the response and the completion code and returns the response data bytes. A minimal Get Self Test Results (IPMI 2.0, section 20.4), whose two response bytes say whether the BMC passed its self test:

public class GetSelfTestResults extends IpmiCommandCoder<GetSelfTestResultsResponseData> {

	@Override
	public NetworkFunction getNetworkFunction() {
		return NetworkFunction.ApplicationRequest;
	}

	@Override
	public byte getCommandCode() {
		return 0x04; // Get Self Test Results (IPMI 2.0, section 20.4)
	}

	@Override
	protected IpmiLanMessage preparePayload(int sequenceNumber) {
		// No request data
		return new IpmiLanRequest(getNetworkFunction(), getCommandCode(), null,
				TypeConverter.intToByte(sequenceNumber));
	}

	@Override
	public GetSelfTestResultsResponseData getResponseData(IpmiMessage message) throws IPMIException {
		byte[] data = validateResponse(message); // throws IPMIException on an error completion code
		return new GetSelfTestResultsResponseData(data); // your own ResponseData implementation
	}
}

GetSelfTestResultsResponseData results = bmc.send(new GetSelfTestResults());

Get Device ID itself is implemented (GetDeviceId^[24], the command behind deviceId()^[25]).

Extension and OEM network functions

NetworkFunction^[26] lists the standard network functions, 00h to 0Bh. A command of another one, Transport (0Ch), Group Extension (2Ch, DCMI), OEM/Group (2Eh) or a controller-specific OEM network function (30h to 3Eh), returns null from getNetworkFunction(), overrides getNetworkFunctionCode(), and builds its request with the IpmiLanRequest constructor that takes the code; its reply is the one under that code plus one. Get DCMI Capabilities Info:

public class GetDcmiCapabilitiesInfo extends IpmiCommandCoder<DcmiCapabilitiesResponseData> {

	private final int parameter;

	public GetDcmiCapabilitiesInfo(int parameter) {
		this.parameter = parameter; // 01h: the supported DCMI capabilities
	}

	@Override
	public NetworkFunction getNetworkFunction() {
		return null; // not in the enumeration: getNetworkFunctionCode() is what is sent
	}

	@Override
	public int getNetworkFunctionCode() {
		return 0x2C; // Group Extension
	}

	@Override
	public byte getCommandCode() {
		return 0x01; // Get DCMI Capabilities Info
	}

	@Override
	protected IpmiLanMessage preparePayload(int sequenceNumber) {
		// The DCMI group extension identification (DCh), then the parameter selector
		byte[] data = { (byte) 0xDC, (byte) parameter };
		return new IpmiLanRequest(getNetworkFunctionCode(), getCommandCode(), data,
				TypeConverter.intToByte(sequenceNumber));
	}

	@Override
	public DcmiCapabilitiesResponseData getResponseData(IpmiMessage message) throws IPMIException {
		return new DcmiCapabilitiesResponseData(validateResponse(message)); // your own ResponseData
	}
}

When the BMC answers it with an error completion code, the IpmiCompletionCodeException of send() has a null networkFunction(). To send such a request once, without writing a class, use raw().