Package org.metricshub.ipmi.core.api.sync

Class IpmiConnector

java.lang.Object
org.metricshub.ipmi.core.api.sync.IpmiConnector
public class IpmiConnector extends Object

Synchronous API for connecting to BMC via IPMI.


Creating connection consists of the following steps:

Send commands with sendMessage(ConnectionHandle, IpmiCommandCoder), which returns the typed response of the command, and close the session with closeSession(ConnectionHandle), in a finally block: BMCs have few session slots.

When done with work, clean up via tearDown()


  • Constructor Details

  • Method Details

    • createConnection

      public ConnectionHandle createConnection(InetAddress address) throws IOException
      Creates connection to the remote host on default IPMI port.
      Parameters:
      address - - InetAddress of the remote host
      Returns:
      handle to the connection to the remote host
      Throws:
      IOException - when the connection cannot be created

    • createConnection

      public ConnectionHandle createConnection(InetAddress address, int port) throws IOException
      Creates connection to the remote host on specified port.
      Parameters:
      address - - InetAddress of the remote host
      port - - remote UDP port
      Returns:
      handle to the connection to the remote host
      Throws:
      IOException - when the connection cannot be created

    • createConnection

      public ConnectionHandle createConnection(InetAddress address, CipherSuite cipherSuite, PrivilegeLevel privilegeLevel) throws IOException
      Creates connection to the remote host, with pre set CipherSuite and PrivilegeLevel, skipping the getAvailableCipherSuites and getChannelAuthenticationCapabilities phases.
      Parameters:
      address - - InetAddress of the remote host
      cipherSuite - - the cipher suite of the session
      privilegeLevel - - the privilege level requested for the session
      Returns:
      handle to the connection to the remote host
      Throws:
      IOException - when the connection cannot be created

    • createConnection

      public ConnectionHandle createConnection(InetAddress address, int port, CipherSuite cipherSuite, PrivilegeLevel privilegeLevel) throws IOException
      Creates connection to the remote host, with pre set CipherSuite and PrivilegeLevel, skipping the getAvailableCipherSuites and getChannelAuthenticationCapabilities phases.
      Parameters:
      address - - InetAddress of the remote host
      port - - remote UDP port
      cipherSuite - - the cipher suite of the session
      privilegeLevel - - the privilege level requested for the session
      Returns:
      handle to the connection to the remote host
      Throws:
      IOException - when the connection cannot be created

    • getAvailableCipherSuites

      public List<CipherSuite> getAvailableCipherSuites(ConnectionHandle connectionHandle) throws Exception
      Gets CipherSuites available for the connection with the remote host.
      Parameters:
      connectionHandle - ConnectionHandle to the connection created before
      Returns:
      list of the CipherSuites that are allowed during the connection
      Throws:
      Ipmi20UnsupportedException - when the BMC does not support IPMI 2.0 (RMCP+): Get Channel Authentication Capabilities, sent first in the IPMI v1.5 format, reports no IPMI v2.0 connections
      Exception - when sending message to the managed system fails
      See Also:

    • getChannelAuthenticationCapabilities

      public GetChannelAuthenticationCapabilitiesResponseData getChannelAuthenticationCapabilities(ConnectionHandle connectionHandle, CipherSuite cipherSuite, PrivilegeLevel requestedPrivilegeLevel) throws Exception
      Declares the cipher suite and the privilege of the session, and returns the authentication capabilities of the remote host that getAvailableCipherSuites(ConnectionHandle) read (requested at the User level): sends nothing.
      Parameters:
      connectionHandle - - ConnectionHandle associated with the host
      cipherSuite - - CipherSuite that will be used during the connection
      requestedPrivilegeLevel - - PrivilegeLevel that is requested for the session
      Returns:
      - GetChannelAuthenticationCapabilitiesResponseData
      Throws:
      ConnectionException - when connection is in the state that does not allow to perform this operation.
      Exception - when the state machine fails

    • openSession

      public Session openSession(ConnectionHandle connectionHandle, String username, String password, byte[] bmcKey) throws Exception
      Establishes the session with the remote host, and raises it to the requested privilege when that is Operator or Administrator (Set Session Privilege Level, IPMI 2.0 section 22.18: every session starts at User). For PrivilegeLevel.MaximumAvailable, the session is requested at Administrator, then at Operator and at User when the BMC refuses the role to the account, and set to User right after the handshake: the caller raises it when a command needs more.
      Parameters:
      connectionHandle - - ConnectionHandle associated with the remote host.
      username - - the username
      password - - password matching the username
      bmcKey - - the key that should be provided if the two-key authentication is enabled, null otherwise.
      Returns:
      object representing newly created Session
      Throws:
      ConnectionException - when connection is in the state that does not allow to perform this operation, or no reply came after all the tries
      SessionException - when the BMC refuses to raise the session to the requested privilege: the session is closed, and the cause is the IPMIException of the completion code
      Exception - when sending message to the managed system or initializing one of the cipherSuite's algorithms fails

    • openSession

      public Session openSession(ConnectionHandle connectionHandle, String username, byte[] password, byte[] bmcKey) throws Exception
      Establishes the session with the remote host, with the password as bytes: the caller can then clear them once the session is open, which an immutable String does not allow. When the requested privilege is Operator or Administrator, the session is raised to it with Set Session Privilege Level right after the handshake (IPMI 2.0 section 22.18: every session starts at User); a refusal closes the session. For PrivilegeLevel.MaximumAvailable, the session is requested at Administrator, then at Operator and at User when the BMC refuses the role to the account, and set to User right after the handshake: the caller raises it when a command needs more.
      Parameters:
      connectionHandle - - ConnectionHandle associated with the remote host.
      username - - the username
      password - - password matching the username, as sent to the BMC (UTF-8 for a text password), at most 20 bytes
      bmcKey - - the key that should be provided if the two-key authentication is enabled, null otherwise.
      Returns:
      object representing newly created Session
      Throws:
      ConnectionException - when connection is in the state that does not allow to perform this operation, or no reply came after all the tries
      SessionException - when the BMC refuses to raise the session to the requested privilege: the session is closed, and the cause is the IPMIException of the completion code
      Exception - when sending message to the managed system or initializing one of the cipherSuite's algorithms fails

    • getExistingSessionForCriteria

      public Session getExistingSessionForCriteria(InetAddress remoteAddress, int remotePort, String user)
      Returns session already bound to given connection handle fulfilling given criteria.
      Parameters:
      remoteAddress - IP addres of the managed system
      remotePort - UDP port of the managed system
      user - IPMI user for whom the connection is established
      Returns:
      session object fulfilling given criteria, or null if no session was registered for such connection.

    • closeSession

      public void closeSession(ConnectionHandle connectionHandle) throws Exception
      Closes the session with the remote host if it is currently in open state, and wipes the password and the BMC key (Kg) the handle keeps.
      Parameters:
      connectionHandle - - ConnectionHandle associated with the remote host.
      Throws:
      ConnectionException - when connection is in the state that does not allow to perform this operation.
      Exception - when sending message to the managed system or initializing one of the cipherSuite's algorithms fails

    • sendMessage

      public ResponseData sendMessage(ConnectionHandle connectionHandle, PayloadCoder request) throws Exception
      Sends the IPMI message to the remote host.
      Parameters:
      connectionHandle - - ConnectionHandle associated with the remote host.
      request - - PayloadCoder containing the request to be sent
      Returns:
      ResponseData for the request
      Throws:
      ConnectionException - when connection is in the state that does not allow to perform this operation.
      Exception - when sending message to the managed system or initializing one of the cipherSuite's algorithms fails

    • sendMessage

      public <R extends ResponseData> R sendMessage(ConnectionHandle connectionHandle, IpmiCommandCoder<R> request) throws Exception
      Sends the IPMI command to the remote host and returns its typed response.
      Type Parameters:
      R - the type of the response data of the command
      Parameters:
      connectionHandle - - ConnectionHandle associated with the remote host.
      request - - the command to send
      Returns:
      the response data of the command
      Throws:
      ConnectionException - when connection is in the state that does not allow to perform this operation.
      IPMIException - when the BMC answers with an error completion code
      Exception - when sending message to the managed system or initializing one of the cipherSuite's algorithms fails

    • sendMessage

      public <R extends ResponseData> R sendMessage(ConnectionHandle connectionHandle, IpmiCommandCoder<R> request, int resends) throws Exception
      Sends the IPMI command to the remote host with its own number of resends when no reply comes, instead of getRetries(): 0 for a command the BMC must not receive twice (a chassis reset, whose reply can be lost after the BMC carried it out). The limit also covers a C3h reply (timeout on the BMC side, response unavailable), which says nothing about what was done; a busy reply, which says the command was not carried out, is still retried getRetries() times.
      Type Parameters:
      R - the type of the response data of the command
      Parameters:
      connectionHandle - - ConnectionHandle associated with the remote host.
      request - - the command to send
      resends - how many times the command is sent again when no reply comes within the timeout, 0 to send it once
      Returns:
      the response data of the command
      Throws:
      ConnectionException - when connection is in the state that does not allow to perform this operation, or no reply came
      IPMIException - when the BMC answers with an error completion code
      Exception - when sending message to the managed system or initializing one of the cipherSuite's algorithms fails

    • sendOneWayMessage

      public void sendOneWayMessage(ConnectionHandle connectionHandle, PayloadCoder request) throws Exception
      Sends the IPMI message to the remote host and doesn't wait for any response.
      Parameters:
      connectionHandle - - ConnectionHandle associated with the remote host.
      request - - PayloadCoder containing the request to be sent
      Throws:
      ConnectionException - when connection is in the state that does not allow to perform this operation.
      Exception - when sending message to the managed system or initializing one of the cipherSuite's algorithms fails

    • retryMessage

      public ResponseData retryMessage(ConnectionHandle connectionHandle, byte tag, PayloadType messagePayloadType) throws Exception
      Re-sends message with given tag having given PayloadType, using passed ConnectionHandle.
      Parameters:
      connectionHandle - - ConnectionHandle associated with the remote host.
      tag - - tag of the message to retry
      messagePayloadType - - PayloadType of the message that should be retried
      Returns:
      ResponseData for the re-sent request or null if message could not be resent.
      Throws:
      Exception - when sending message to the managed system fails

    • registerIncomingMessageListener

      public void registerIncomingMessageListener(InboundMessageListener listener)
      Registers InboundMessageListener that will react on any request sent from remote system to the application.
      Parameters:
      listener - listener to be registered.

    • unregisterIncomingMessageListener

      public void unregisterIncomingMessageListener(InboundMessageListener listener)
      Unregisters an InboundMessageListener, which then no longer receives the requests of the remote systems.
      Parameters:
      listener - listener to be unregistered.

    • closeConnection

      public void closeConnection(ConnectionHandle handle)
      Closes the connection with the given handle, without closing its session: the requests still waiting for a reply on the connection fail, with a ConnectionException or an IllegalStateException. The password and the BMC key (Kg) the handle keeps are wiped.
      Parameters:
      handle - the handle of the connection

    • tearDown

      public void tearDown()
      Finalizes the connector and closes all connections, without closing their sessions: the requests still waiting for a reply fail, with a ConnectionException or an IllegalStateException. The password and the BMC key (Kg) of the sessions are wiped.

    • setTimeout

      public void setTimeout(ConnectionHandle handle, int timeout)
      Changes the timeout value for connection with the given handle.
      Parameters:
      handle - - ConnectionHandle associated with the remote host.
      timeout - - new timeout value in ms

    • getTimeout

      public int getTimeout(ConnectionHandle handle)
      Returns the timeout of a single message on the connection with the given handle.
      Parameters:
      handle - - ConnectionHandle associated with the remote host.
      Returns:
      the timeout in ms after which a message without a reply is reported as timed out

    • getRetries

      public int getRetries()
      Returns how many times a message without a reply is sent again.
      Returns:
      the number of resends

    • setRetries

      public void setRetries(int retries)
      Sets how many times a message without a reply is sent again, or a login whose step got no reply is started again from Open Session.
      Parameters:
      retries - the number of resends, 0 to send every message once
      Throws:
      IllegalArgumentException - when negative

    • setTimeout

      public void setTimeout(int timeout)
      Sets the timeout of the messages of the connections created from now on; setTimeout(ConnectionHandle, int) changes it for an existing connection. 5 000 ms by default.
      Parameters:
      timeout - the time in milliseconds after which a message without a reply is reported as timed out
      Throws:
      IllegalArgumentException - when the timeout is less than one millisecond