Package org.metricshub.ipmi.client

Class IpmiClient.Builder

java.lang.Object
org.metricshub.ipmi.client.IpmiClient.Builder
Enclosing class:
IpmiClient
public static final class IpmiClient.Builder extends Object
Builds an IpmiClient: the BMC, the credentials and the session settings. build() validates them and touches no network.

  • Method Details

    • port

      public IpmiClient.Builder port(int udpPort)
      Sets the UDP port of the BMC; 623 by default.
      Parameters:
      udpPort - the port, 1 to 65535
      Returns:
      this builder
      Throws:
      IllegalArgumentException - when the port is not between 1 and 65535

    • credentials

      public IpmiClient.Builder credentials(String userName, char[] userPassword)
      Sets the user name and password of the session. The password is not copied: the caller can wipe it once the client is closed. Required by every operation but IpmiClient.capabilities().
      Parameters:
      userName - the user name, at most 16 bytes in UTF-8
      userPassword - the password, at most 20 bytes in UTF-8
      Returns:
      this builder

    • bmcKey

      public IpmiClient.Builder bmcKey(byte[] key)
      Sets the BMC key (Kg) of the two-key login, as raw bytes, for a BMC whose key is set. A key of zero bytes only, the default value of a BMC, is treated as no key. The array is not copied: the caller can wipe it once the client is closed.
      Parameters:
      key - the key, at most 20 bytes, or null for the usual single-key login
      Returns:
      this builder

    • privilege

      public IpmiClient.Builder privilege(PrivilegeLevel level)
      Sets the maximum privilege of the session, requested at Open Session and RAKP 1. The specification starts every session at User (IPMI 2.0 section 22.18): for Operator and Administrator, the client raises it with Set Session Privilege Level right after the handshake. A BMC that refuses the level fails the operation that opens the session with IpmiAuthenticationException; another failure of that command (a busy BMC) fails it with IpmiClientException.

      User, the default, is enough for every read operation of the BMC itself; most BMCs need Operator, some Administrator, for the sensors and FRUs of the controllers behind the BMC, which it reaches with Send Message. Operator is needed for the control operations (power, identify), Administrator for Serial over LAN on most BMCs.

      MaximumAvailable requests the highest level the account is allowed, then runs the session at User and raises it only when the BMC refuses a command for insufficient privilege (D4h): to Operator, then to Administrator, and the refused command, which the BMC did not carry out, is sent again. A level the BMC refuses (80h, 81h) is the ceiling of the session, remembered for its lifetime, and the D4h reaches the caller as it does at a fixed level. The sensors of controllers other than the BMC, which some BMCs serve at the Operator or Administrator level only, are then read with any account that has the level, without running the whole session at it.

      Parameters:
      level - the privilege level: User, Operator, Administrator or MaximumAvailable (Callback, at which no operation works, is refused)
      Returns:
      this builder
      Throws:
      IllegalArgumentException - for Callback

    • cipherSuites

      public IpmiClient.Builder cipherSuites(int... ids)
      Sets the cipher suites the client may use, by order of preference: the first one the BMC offers is used. Default: 17, 3, 8, 16, 2, 7, 12, 11. The suites without integrity (0, 1, 6, 15) and the xRC4 suites, which the library does not implement (4, 5, 9, 10, 13, 14, 18, 19), are refused.
      Parameters:
      ids - the suite IDs (IPMI 2.0 table 22-20)
      Returns:
      this builder
      Throws:
      IllegalArgumentException - when no suite is given, or a suite is not a standard suite (0 to 19), has no integrity (0, 1, 6, 15) or uses xRC4 (4, 5, 9, 10, 13, 14, 18, 19)

    • cipherSuite

      public IpmiClient.Builder cipherSuite(int id)
      Uses exactly the given cipher suite, without asking the BMC which ones it offers: saves the Get Channel Authentication Capabilities and Get Channel Cipher Suites round trips with a BMC known to support it. An IPMI 1.5-only BMC then fails with IpmiConnectionException (no reply to Open Session) instead of IpmiClientException.
      Parameters:
      id - the suite ID (IPMI 2.0 table 22-20), one with integrity and without xRC4
      Returns:
      this builder
      Throws:
      IllegalArgumentException - when the suite is not a standard suite (0 to 19), has no integrity (0, 1, 6, 15) or uses xRC4 (4, 5, 9, 10, 13, 14, 18, 19), which the library does not implement

    • timeout

      public IpmiClient.Builder timeout(Duration deadline)
      Sets the overall deadline of each operation, session setup included; 2 minutes by default. Each operation builder can override it.
      Parameters:
      deadline - the deadline
      Returns:
      this builder
      Throws:
      IllegalArgumentException - when the duration is shorter than one millisecond or longer than Integer.MAX_VALUE milliseconds

    • messageTimeout

      public IpmiClient.Builder messageTimeout(Duration duration)
      Sets how long a message waits for its reply before it is sent again; 5 seconds by default.
      Parameters:
      duration - the timeout of a message
      Returns:
      this builder
      Throws:
      IllegalArgumentException - when the duration is shorter than one millisecond or longer than Integer.MAX_VALUE milliseconds

    • retries

      public IpmiClient.Builder retries(int count)
      Sets how many times a message is sent again; 3 by default. A message is sent again at once when it gets no reply within the message timeout or gets a C3h (timeout on the BMC side), and after a random pause of up to 4 seconds when the BMC says it is busy (C0h, node busy, or D2h, initialization in progress); in the session handshake, a busy reply or the RAKP status insufficient resources to create a session is sent again at once. The control operations never send their command again for a lost reply or a C3h (IpmiClient.chassisControl(PowerCommand)), and IpmiClient.raw(int, int) returns a busy or C3h reply instead of sending its request again.
      Parameters:
      count - the number of resends, 0 to send every message once
      Returns:
      this builder
      Throws:
      IllegalArgumentException - when the count is negative

    • keepAlive

      public IpmiClient.Builder keepAlive(Duration period)
      Sets the period of the keep-alive messages that keep the session open between operations; 30 seconds by default. Duration.ZERO disables them: the BMC then expires an idle session after its own timeout (60 seconds by default), and the client finds out only when a request of the next operation gets no reply after all its tries: a read operation is then run again on a new session, any other one fails with IpmiTimeoutException.
      Parameters:
      period - the period, or Duration.ZERO
      Returns:
      this builder
      Throws:
      IllegalArgumentException - when the period is negative, or shorter than one millisecond but not zero

    • sdrCache

      public IpmiClient.Builder sdrCache(boolean enabled)
      Tells whether the client caches the SDR repository it reads, so that IpmiClient.sensors() and IpmiClient.frus() walk it once; enabled by default. Before using the cache, each operation checks with Get SDR Repository Info that the record count and the timestamps of the most recent addition and erase did not change. Disable it for a BMC whose timestamps cannot be trusted.
      Parameters:
      enabled - whether to cache the repository
      Returns:
      this builder

    • build

      public IpmiClient build()
      Validates the settings and creates the client. No session is opened: the first operation that needs one opens it.
      Returns:
      the client, to close when done
      Throws:
      IllegalArgumentException - when the user name is longer than 16 bytes, or the password or the BMC key longer than 20 bytes