Package org.metricshub.ipmi.core.api.async

Class IpmiAsyncConnector

java.lang.Object
org.metricshub.ipmi.core.api.async.IpmiAsyncConnector
All Implemented Interfaces:
ConnectionListener
public class IpmiAsyncConnector extends Object implements ConnectionListener

Asynchronous API for connecting to BMC via IPMI.

Creating connection consists of the following steps:

Register a listener for the responses with registerListener(IpmiResponseListener), then send messages with sendMessage(ConnectionHandle, PayloadCoder, boolean): the response to a message that is not one-way, or its failure (an IpmiError), reaches the listeners with the tag that sendMessage() returned.


To close session call closeSession(ConnectionHandle)


  • Field Details

    • FAILED_TO_RECEIVE_ANSWER_CAUSE_MESSAGE

      public static final String FAILED_TO_RECEIVE_ANSWER_CAUSE_MESSAGE
      See Also:

    • DEFAULT_RETRIES

      public static final int DEFAULT_RETRIES
      Number of times a message without a reply is sent again, until setRetries(int) changes it.
      See Also:

  • Constructor Details

    • IpmiAsyncConnector

      public IpmiAsyncConnector(int port) throws IOException
      Starts IpmiAsyncConnector and initiates the ConnectionManager at the given port. The wildcard IP address will be used.
      Parameters:
      port - - the port that will be used by IpmiAsyncConnector to communicate with the remote hosts.
      Throws:
      IOException - when the port cannot be bound

    • IpmiAsyncConnector

      public IpmiAsyncConnector(int port, InetAddress address) throws IOException
      Starts IpmiAsyncConnector and initiates the ConnectionManager at the given port and IP interface.
      Parameters:
      port - - the port that will be used by IpmiAsyncConnector to communicate with the remote hosts.
      address - - the IP address that will be used by IpmiAsyncConnector to communicate with the remote hosts.
      Throws:
      IOException - when the port cannot be bound

    • IpmiAsyncConnector

      public IpmiAsyncConnector(int port, long pingPeriod) throws IOException
      Starts IpmiAsyncConnector and initiates the ConnectionManager at the given port and ping period.
      Parameters:
      port - the port that will be used by IpmiAsyncConnector to communicate with the remote hosts.
      pingPeriod - the period between sending keep-alive messages to the remote host.
      Throws:
      IOException - When ConnectionManager cannot be created due to an IO error.

  • Method Details

    • 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

    • getRetries

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

    • setTimeout

      public void setTimeout(int timeout)
      Sets the timeout of the messages of the connections created from now on.
      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

    • createConnection

      public ConnectionHandle createConnection(InetAddress address, int port) throws IOException
      Creates connection to the remote host.
      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, 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 int sendMessage(ConnectionHandle connectionHandle, PayloadCoder request, boolean isOneWay) 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
      isOneWay - - true for a message whose reply nobody waits for (the reply is discarded, and its timeout is not reported), false to receive the reply through the registered listeners
      Returns:
      the tag of the message, which the response delivered to the listeners carries (IpmiResponse.getTag())
      Throws:
      ConnectionException - when the session is not open, or the message window stayed full, at every try
      IllegalStateException - when the connection is closed
      Exception - when sending message to the managed system or initializing one of the cipherSuite's algorithms fails

    • retry

      public int retry(ConnectionHandle connectionHandle, int tag, PayloadType messagePayloadType) throws ConnectionException
      Attempts to retry sending a message.
      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:
      new tag if message was retried, -1 if operation failed
      Throws:
      ConnectionException - when connection isn't in state where sending commands is allowed

    • registerListener

      public void registerListener(IpmiResponseListener listener)
      Registers the listener so it will be notified of incoming messages.
      Parameters:
      listener - IpmiResponseListener to processResponse

    • unregisterListener

      public void unregisterListener(IpmiResponseListener listener)
      Unregisters the listener so it will no longer receive notifications of received answers.
      Parameters:
      listener - - the IpmiResponseListener to unregister

    • registerIncomingPayloadListener

      public void registerIncomingPayloadListener(InboundMessageListener listener)
      Registers the listener for incoming messages.
      Parameters:
      listener - the InboundMessageListener to register.

    • unregisterIncomingPayloadListener

      public void unregisterIncomingPayloadListener(InboundMessageListener listener)
      Unregisters the listener so it will no longer receive notifications of received messages.
      Parameters:
      listener - the InboundMessageListener to unregister.

    • processResponse

      public void processResponse(ResponseData responseData, int handle, int tag, Exception exception)
      Description copied from interface: ConnectionListener
      Notifies the ConnectionListeners of the one of the following events:
      • response to the request tagged with id arrived
      • request tagged with id timed out
      Specified by:
      processResponse in interface ConnectionListener
      Parameters:
      responseData - - ResponseData specific for the request if it was completed successfully, null if it timed out or an error occured during decoding.
      handle - - the id of the connection that received the message
      tag - - tag of the request-response pair
      exception - - null if everything went correctly or timeout occured, contains exception that occured during decoding if it failed.

    • processRequest

      @Deprecated public void processRequest(IpmiPayload payload)
      Deprecated.
      the connections call processRequest(IpmiPayload, int)
      Notifies the inbound listeners that take the payload from any connection, as 1.2.02 did.
      Specified by:
      processRequest in interface ConnectionListener
      Parameters:
      payload - the payload received

    • processRequest

      public void processRequest(IpmiPayload payload, int handle)
      Description copied from interface: ConnectionListener
      Notifies the ConnectionListener of a payload the remote system sent on its own initiative (Serial over LAN data). Calls ConnectionListener.processRequest(IpmiPayload) by default.
      Specified by:
      processRequest in interface ConnectionListener
      Parameters:
      payload - - the payload received
      handle - - the id of the connection that received the payload

    • closeConnection

      public void closeConnection(ConnectionHandle handle)
      Closes the connection with the given handle, forgets its session, and wipes the credentials the handle keeps. The requests still waiting for a reply on the connection fail with a ConnectionException.
      Parameters:
      handle - the handle of the connection

    • tearDown

      public void tearDown()
      Finalizes the connector, closes all connections, and wipes the credentials of their sessions.

    • 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 given connection.
      Parameters:
      handle - ConnectionHandle of the connection
      Returns:
      the timeout in milliseconds after which a message without a reply is reported as timed out