Repository navigation
Rewrite the documentation with Sentry Maven Skin 8 and a full page set (#113) #124
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,76 @@ | ||
| keywords: chassis status, power state, power on, power off, power restore policy, intrusion, fault, get chassis status | ||
| description: Read the chassis status of a server through its BMC — power state, last power event, power restore policy, faults, intrusion and front panel flags. | ||
|
|
||
| # Chassis Status | ||
|
|
||
| <!-- MACRO{toc|fromDepth=2|toDepth=3|id=toc} --> | ||
|
|
||
| The IPMI **Get Chassis Status** command reports whether the server is powered on, why it last | ||
| changed power state, what it does when mains power returns, and a few fault and front panel | ||
| flags. It is a single request: reading it is fast, and it is a good way to check that the | ||
| credentials work. | ||
|
|
||
| ## As text | ||
|
|
||
| ```java | ||
| String status = IpmiClient.getChassisStatusAsStringResult(config); | ||
| // "System power state is up" or "System power state is down" | ||
| ``` | ||
|
|
||
| The text reports the power state only. | ||
|
|
||
| ## As an object | ||
|
|
||
| ```java | ||
| GetChassisStatusResponseData status = IpmiClient.getChassisStatus(config); | ||
|
|
||
| System.out.println("Power: " + (status.isPowerOn() ? "on" : "off")); | ||
| System.out.println("Restore policy: " + status.getPowerRestorePolicy()); | ||
| System.out.println("Intrusion: " + status.isChassisIntrusionActive()); | ||
| ``` | ||
|
|
||
| [`GetChassisStatusResponseData`](apidocs/org/metricshub/ipmi/core/coding/commands/chassis/GetChassisStatusResponseData.html) | ||
| decodes the response (IPMI 2.0, section 28.2): | ||
|
|
||
| | Method | Meaning | | ||
| | --- | --- | | ||
| | **Current power state** | | | ||
| | `isPowerOn()` | System power is on | | ||
| | `isPowerOverload()` | The system was shut down because of a power overload | | ||
| | `isInterlock()` | A power interlock (a switch that cuts power when the chassis is open) is active | | ||
| | `isPowerFault()` | A fault was detected in the main power subsystem | | ||
| | `isPowerControlFault()` | The power controller tried to change the power state and failed | | ||
| | `getPowerRestorePolicy()` | What happens when mains power returns: `PoweredOff`, `PowerRestored` (back to the previous state) or `PoweredUp` | | ||
| | **Last power event** | | | ||
| | `wasIpmiPowerOn()` | The last power-on was requested through IPMI | | ||
| | `wasPowerFault()` | The last power-down was caused by a power fault | | ||
| | `wasInterlock()` | The last power-down was caused by a power interlock | | ||
| | `wasPowerOverload()` | The last power-down was caused by a power overload | | ||
| | `acFailed()` | Mains (AC) power was lost | | ||
| | **Miscellaneous chassis state** | | | ||
| | `isChassisIntrusionActive()` | The chassis intrusion sensor is active (the case is or was open) | | ||
| | `isFrontPanelLockoutActive()` | The power off and reset buttons of the front panel are disabled | | ||
| | `driveFaultDetected()` | A drive fault was detected | | ||
| | `coolingFaultDetected()` | A cooling or fan fault was detected | | ||
| | `isChassisIdentifyCommandSupported()`, `getChassisIdentifyState()` | Whether the identify LED can be read, and its state: `Off`, `TemporaryOn`, `IndefiniteOn` | | ||
| | **Front panel buttons** (optional in the response) | | | ||
| | `isFrontPanelButtonCapabilitiesSet()` | The BMC returned the front panel button byte; the methods below throw `IllegalAccessException` otherwise | | ||
| | `isPowerOffButtonDisabled()`, `isResetButtonDisabled()`, ... | State of each button, and whether it can be disabled (`...DisableAllowed()`) | | ||
|
|
||
| > [!NOTE] | ||
| > `getChassisIdentifyState()` throws `IllegalAccessError` when | ||
| > `isChassisIdentifyCommandSupported()` is `false`: check it first. `getPowerRestorePolicy()` | ||
| > throws `IllegalArgumentException` when the BMC reports the policy as *unknown* | ||
| > ([#87](https://github.com/metricshub/ipmi-java/issues/87)). | ||
|
|
||
| Not every BMC fills every flag: the intrusion, drive and cooling bits in particular are optional | ||
| in the specification, and a BMC that does not implement them reports `false`. | ||
|
|
||
| ## Controlling the power | ||
|
|
||
| `IpmiClient` only reads. To power the server on or off or reset it, send the | ||
| [`ChassisControl`](apidocs/org/metricshub/ipmi/core/coding/commands/chassis/ChassisControl.html) | ||
| command with the [low-level API](low-level-api.html#sending-commands), in a session opened with | ||
| the **Operator** or **Administrator** privilege. The supported power commands are `PowerDown`, | ||
| `PowerUp` and `HardReset`. Exposing power control in `IpmiClient` is tracked in | ||
| [#104](https://github.com/metricshub/ipmi-java/issues/104). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,117 @@ | ||
| keywords: configuration, ipmiclientconfiguration, credentials, password, bmc key, kg, skipauth, timeout, pingperiod, keep-alive, port | ||
| description: Every option of IpmiClientConfiguration — host and port, credentials, BMC key, skipAuth, the overall timeout and the keep-alive period — with their defaults and exact semantics. | ||
|
|
||
| # Configuration | ||
|
|
||
| <!-- MACRO{toc|fromDepth=2|toDepth=3|id=toc} --> | ||
|
|
||
| Every call of [`IpmiClient`](apidocs/org/metricshub/ipmi/client/IpmiClient.html) takes an | ||
| [`IpmiClientConfiguration`](apidocs/org/metricshub/ipmi/client/IpmiClientConfiguration.html), | ||
| which carries the target, the credentials and the timing options. It is a plain mutable object: | ||
| build it once per BMC and reuse it for every call; the client never modifies it. | ||
|
|
||
| ## Constructors | ||
|
|
||
| ```java | ||
| // host, user, password, BMC key, skipAuth, timeout (s) | ||
| new IpmiClientConfiguration("bmc.example.com", "monitor", password, null, false, 120); | ||
|
|
||
| // ... with a UDP port other than 623 | ||
| new IpmiClientConfiguration("bmc.example.com", 6230, "monitor", password, null, false, 120); | ||
|
|
||
| // ... with a keep-alive period (ms), 0 to disable the keep-alive messages | ||
| new IpmiClientConfiguration("bmc.example.com", "monitor", password, null, false, 120, 0); | ||
| ``` | ||
|
|
||
| Every option also has a setter (`setPort(int)`, `setPingPeriod(long)`, ...), so the options of | ||
| one constructor can be combined with those of another. | ||
|
|
||
| ## Options | ||
|
|
||
| | Option | Default | Details | | ||
| | --- | --- | --- | | ||
| | `hostname` | required | [Host and port](#host-and-port) | | ||
| | `port` | `623` | [Host and port](#host-and-port) | | ||
| | `username`, `password` | required | [Credentials](#credentials) | | ||
| | `bmcKey` | `null` | [BMC key](#bmc-key) | | ||
| | `skipAuth` | required | [skipAuth](#skipauth) | | ||
| | `timeout` | required, in **seconds** | [Timeout](#timeout) | | ||
| | `pingPeriod` | `-1`: 30 000 ms | [Keep-alive](#keep-alive) | | ||
|
|
||
| ### Host and port | ||
|
|
||
| `hostname` is the host name or the IP address (IPv4 or IPv6) of the **BMC**, not of the server's | ||
| operating system. It is resolved with `InetAddress.getByName()` at each call. | ||
|
|
||
| `port` is the UDP port of the BMC, **623** by default. Change it only for a BMC behind a NAT | ||
| or a proxy that forwards another port to 623. The local UDP port is always an ephemeral one, | ||
| chosen by the operating system for each session. | ||
|
|
||
| ### Credentials | ||
|
|
||
| `username` and `password` are the IPMI account of the BMC: see | ||
| [Preparing the BMC](preparing-the-bmc.html#creating-the-account). The password is a `char[]`; | ||
| the library converts it to a `String` internally to open the session and does not clear the | ||
| array, so clear it yourself once you no longer need the configuration. | ||
|
|
||
| The client opens every session with the **User** privilege level, which is enough for every | ||
| `IpmiClient` method. | ||
|
|
||
| ### BMC key | ||
|
|
||
| `bmcKey` is the **BMC key (Kg)** of the BMC, as raw bytes, for BMCs configured with *two-key* | ||
| logins. Leave it `null` (the default on virtually every BMC): the session keys are then derived | ||
| from the password. See [Preparing the BMC](preparing-the-bmc.html#bmc-key-kg). | ||
|
|
||
| ### skipAuth | ||
|
|
||
| Despite its name, `skipAuth` does **not** skip authentication: the session is always | ||
| authenticated with the user name and password (RAKP handshake). It chooses how the cipher suite is | ||
| picked: | ||
|
|
||
| | `skipAuth` | Before opening the session | Cipher suite | Privilege | | ||
| | --- | --- | --- | --- | | ||
| | `false` (recommended) | Get Channel Cipher Suites, then Get Channel Authentication Capabilities | Picked from the BMC's list, [by position](preparing-the-bmc.html#how-ipmiclient-chooses-the-suite) | User | | ||
| | `true` | Nothing: the session is opened directly | Always **3** (RAKP-HMAC-SHA1, HMAC-SHA1-96, AES-CBC-128) | User | | ||
|
|
||
| Use `true` to force suite 3 on a BMC whose suite list would make the position rule pick a suite | ||
| the client does not implement, or to save two round trips per call. | ||
|
|
||
| ### Timeout | ||
|
|
||
| `timeout` is the **overall deadline of each `IpmiClient` call, in seconds**: opening the session, | ||
| every command, and closing the session. When it expires, the call is cancelled and throws | ||
| `java.util.concurrent.TimeoutException`. Walking a large SDR repository or reading many FRUs can | ||
| take tens of seconds on a slow BMC: 120 s is a safe value. | ||
|
|
||
| `getFrusAndSensorsAsStringResult()` makes two calls (FRUs, then sensors), each with this | ||
| deadline, so it can take up to twice the timeout. | ||
|
|
||
| The timeout of each **message** is a different setting, 5 minutes by default; see | ||
| [Timeouts and Errors](timeouts-and-errors.html). | ||
|
|
||
| ### Keep-alive | ||
|
|
||
| While a session is open, the client sends a no-op message (Get Channel Authentication | ||
| Capabilities) every `pingPeriod` **milliseconds**, so that the BMC does not close the session for | ||
| inactivity during a long collection. | ||
|
|
||
| | `pingPeriod` | Behavior | | ||
| | --- | --- | | ||
| | `-1` (default) | The `pingPeriod` of [`connection.properties`](timeouts-and-errors.html#library-wide-defaults): 30 000 ms | | ||
|
There was a problem hiding this comment.
Fresh evidence after the earlier fix is that the final tree restores the claim that AGENTS.md reference: AGENTS.md:L35-L35 Useful? React with 👍 / 👎. |
||
| | `> 0` | One keep-alive message every `pingPeriod` ms | | ||
| | `0` (or any other negative value) | No keep-alive messages | | ||
|
|
||
| Each `IpmiClient` call opens its own session and closes it when it is done, so the keep-alive | ||
| only matters for calls that last longer than the BMC's session inactivity timeout (typically | ||
| 60 s). Disable it (`0`) to keep the traffic to the strict minimum. | ||
|
|
||
| ## Thread safety | ||
|
|
||
| `IpmiClient` methods are static and keep no state between calls: each call creates its own | ||
| connector, local UDP port, session and worker thread. Calls can run in parallel, for different | ||
| BMCs. Parallel sessions against the **same BMC** are not reliable: BMCs accept a limited number of | ||
| sessions and drop replies under load, and parallel sessions from one JVM lose far more replies | ||
| than the same sessions from separate processes | ||
| ([#97](https://github.com/metricshub/ipmi-java/issues/97)). Query a given BMC from one thread at a | ||
| time. | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.