Package org.metricshub.ipmi.core.api.sol

Class SerialOverLan

java.lang.Object
org.metricshub.ipmi.core.api.sol.SerialOverLan
All Implemented Interfaces:
Closeable, AutoCloseable
public class SerialOverLan extends Object implements Closeable
A Serial over LAN (SOL) console in a session of the protocol core: activates the SOL payload, reads and writes the serial port of the server, and invokes the serial port operations. Applications that use IpmiClient open a console with sol().open() instead.

  • Constructor Details

    • SerialOverLan

      public SerialOverLan(IpmiConnector connector, String remoteHost, int remotePort, String user, String password, CipherSuiteSelectionHandler cipherSuiteSelectionHandler) throws SOLException, SessionException
      Creates connection with IPMI using given IpmiConnector, connected to remote machine on given address and port, and opens a new Session for SOL communication. The console owns the connector: closing the console, or failing to open it, tears the connector down.
      Parameters:
      connector - IpmiConnector that will be used for communication
      remoteHost - the host name or IP address of the BMC
      remotePort - UDP port number of the remote server
      user - IPMI user name
      password - IPMI password
      cipherSuiteSelectionHandler - CipherSuiteSelectionHandler that will allow to select CipherSuite among available ones.
      Throws:
      SOLException - when the SOL payload cannot be activated
      SessionException - when the session cannot be opened, or the account is not allowed the Administrator privilege

    • SerialOverLan

      public SerialOverLan(IpmiConnector connector, String remoteHost, int remotePort, String user, String password, byte[] bmcKey, CipherSuiteSelectionHandler cipherSuiteSelectionHandler) throws SOLException, SessionException
      Creates connection with IPMI using given IpmiConnector, connected to remote machine on given address and port, and opens a new Session for SOL communication, with the BMC key of a BMC configured for two-key logins. The console owns the connector: closing the console, or failing to open it, tears the connector down.
      Parameters:
      connector - IpmiConnector that will be used for communication
      remoteHost - the host name or IP address of the BMC
      remotePort - UDP port number of the remote server
      user - IPMI user name
      password - IPMI password, sent in UTF-8
      bmcKey - the BMC key (Kg) as raw bytes, at most 20, or null for a one-key login
      cipherSuiteSelectionHandler - CipherSuiteSelectionHandler that will allow to select CipherSuite among available ones.
      Throws:
      SOLException - when the SOL payload cannot be activated
      SessionException - when the session cannot be opened, or the account is not allowed the Administrator privilege

    • SerialOverLan

      public SerialOverLan(IpmiConnector connector, String remoteHost, String user, String password, CipherSuiteSelectionHandler cipherSuiteSelectionHandler) throws SOLException, SessionException
      Creates connection with IPMI using given IpmiConnector, connected to remote machine on given address and default IPMI port, and opens a new Session for SOL communication. The console owns the connector: closing the console, or failing to open it, tears the connector down.
      Parameters:
      connector - IpmiConnector that will be used for communication
      remoteHost - the host name or IP address of the BMC
      user - IPMI user name
      password - IPMI password
      cipherSuiteSelectionHandler - CipherSuiteSelectionHandler that will allow to select CipherSuite among available ones.
      Throws:
      SOLException - when the SOL payload cannot be activated
      SessionException - when the session cannot be opened, or the account is not allowed the Administrator privilege

    • SerialOverLan

      public SerialOverLan(IpmiConnector connector, Session session) throws SOLException, SessionException
      Tries to open SOL communication on given existing session. When it appears that separate session must be opened to handle SOL messages (for example SOL payload must be activated on separate port), the new connection and session are automatically established. Closing the console leaves the given session and the connector open, and closes the session it opened, if any.
      Parameters:
      connector - IpmiConnector that will be used for communication
      session - Existing session that should be reused (if possible) for SOL communication.
      Throws:
      SOLException - when the SOL payload cannot be activated
      SessionException - when the session on the SOL payload port cannot be opened

    • SerialOverLan

      public SerialOverLan(IpmiConnector connector, Session session, PrivilegeLevel level, PrivilegeLevel ceiling) throws SOLException, SessionException
      Tries to open SOL communication on given existing session, like SerialOverLan(IpmiConnector, Session), for a session opened with PrivilegeLevel.MaximumAvailable whose level its owner keeps: the console raises it from the given level, when the BMC refuses to activate the payload at that level, as far as the given ceiling only. The levels do not matter for a session opened at a fixed level, and do not apply to the session the console opens on the port of the payload, which it raises from User as far as the account allows.
      Parameters:
      connector - IpmiConnector that will be used for communication
      session - Existing session that should be reused (if possible) for SOL communication.
      level - the level the session runs at: User, Operator or Administrator
      ceiling - the highest level the console may raise the session to; the given level to never raise it
      Throws:
      SOLException - when the SOL payload cannot be activated
      SessionException - when the session on the SOL payload port cannot be opened

  • Method Details

    • getRaisedPrivilegeLevel

      public PrivilegeLevel getRaisedPrivilegeLevel()
      Returns the privilege the console raised the session of the payload to, when that session was opened with PrivilegeLevel.MaximumAvailable and the BMC refused to activate the payload at its level: the owner of the session (see getConnectionHandle()) runs it at that level from then on.
      Returns:
      Operator or Administrator, or null when the console did not raise the session

    • getConnectionHandle

      public ConnectionHandle getConnectionHandle()
      Returns the connection the console exchanges its packets on: the one of the session it was given, or the one of the session it opened on the port of the payload when the BMC serves SOL on another port.
      Returns:
      the connection handle of the payload session

    • writeByte

      public boolean writeByte(byte singleByte)
      Writes single byte to the port. This operation blocks until all data can be sent to remote server and is either accepted or rejected by the server.
      Parameters:
      singleByte - a byte to write
      Returns:
      true if byte was successfully sent and acknowledged by remote server, false otherwise.

    • writeBytes

      public boolean writeBytes(byte[] buffer)
      Writes bytes array to the port, in packets of the size the BMC accepts. This operation blocks until all data can be sent to remote server and is either accepted or rejected by the server. When it fails, the server may have received the first bytes already.
      Parameters:
      buffer - an array of bytes to write
      Returns:
      true if all bytes were successfully sent and acknowledged by remote server, false otherwise.

    • writeInt

      public boolean writeInt(int singleInt)
      Writes single integer (in range from 0 to 255) to the port. This operation blocks until all data can be sent to remote server and is either accepted or rejected by the server.
      Parameters:
      singleInt - an integer value to write (must be in range from 0 to 255)
      Returns:
      true if integer was successfully sent and acknowledged by remote server, false otherwise.

    • writeIntArray

      public boolean writeIntArray(int[] buffer)
      Writes integers (in range from 0 to 255) array to the port. This operation blocks until all data can be sent to remote server and is either accepted or rejected by the server.
      Parameters:
      buffer - an array of integer values to write (each must be in range from 0 to 255)
      Returns:
      true if all integers were successfully sent and acknowledged by remote server, false otherwise.

    • writeString

      public boolean writeString(String string)
      Writes String to port, using platform's default Charset when converting String to byte array. This operation blocks until all data can be sent to remote server and is either accepted or rejected by the server.
      Parameters:
      string - a string to write to the port.
      Returns:
      true if whole string was successfully sent and acknowledged by remote server, false otherwise.

    • writeString

      public boolean writeString(String string, Charset charset)
      Writes String to port, using given Charset when converting String to byte array. This operation blocks until all data can be sent to remote server and is either accepted or rejected by the server.
      Parameters:
      string - a string to write to port
      charset - Charset that the string is encoded in
      Returns:
      true if whole string was successfully sent and acknowledged by remote server, false otherwise.

    • available

      public int available()
      Returns the number of characters received from the BMC that a read returns without waiting.
      Returns:
      the number of bytes buffered, 0 when none

    • getSession

      public Session getSession()
      Returns the session the console exchanges its packets in: the session it was given, or the one it opened on the port of the payload when the BMC serves SOL on another port.
      Returns:
      the session of the payload

    • readBytes

      public byte[] readBytes()
      Read all available bytes from the port. Returns immediately, without waiting for data to be available.
      Returns:
      all bytes that could be read or empty array if no bytes were available.

    • readBytes

      public byte[] readBytes(int byteCount)
      Reads at max given number of bytes from the port. Returns immediately, without waiting for data to be available.
      Parameters:
      byteCount - maximum number of bytes that should be read
      Returns:
      byte array containing bytes that could be read, but no more than given byteCount. Returns empty array if no bytes were available.

    • readBytes

      public byte[] readBytes(int byteCount, int timeout)
      Reads at max given number of bytes from the port. This operation blocks until given number of bytes is available to be read, the buffer of 64 KiB is full, or the given timeout is hit.
      Parameters:
      byteCount - maximum number of bytes that should be read.
      timeout - maximum time in milliseconds that we want to wait for all available bytes
      Returns:
      byte array containing bytes that could be read, but no more than byteCount. When the timeout is hit, returns just bytes that were available or empty array if no bytes were available.

    • readIntArray

      public int[] readIntArray()
      Reads all available bytes from the port as integer (in range from 0 to 255) values array. Returns immediately, without waiting for data to be available.
      Returns:
      all bytes that could be read as int array (each value in range from 0 to 255) or empty array if no data was available.

    • readIntArray

      public int[] readIntArray(int byteCount)
      Reads at max given number of integer values (in range from 0 to 255) from the port. Returns immediately, without waiting for data to be available.
      Parameters:
      byteCount - maximum number of bytes that should be read
      Returns:
      integer array containing integer values that could be read, but no more than given byteCount (each value in range from 0 to 255). Returns empty array if no data was available.

    • readIntArray

      public int[] readIntArray(int byteCount, int timeout)
      Reads at max given number of integer values (in range from 0 to 255) from the port. This operation blocks until given number of bytes is available to be read, the buffer of 64 KiB is full, or the given timeout is hit.
      Parameters:
      byteCount - maximum number of bytes that should be read.
      timeout - maximum time in milliseconds that we want to wait for all available data
      Returns:
      integer array containing integer values that could be read, but no more than byteCount (each value in range from 0 to 255). When the timeout is hit, returns just data that was available or empty array if no data was available.

    • readString

      public String readString()
      Read all available bytes from the port and converts them to String using platform's default Charset. Returns immediately, without waiting for data to be available.
      Returns:
      all bytes that could be read as String.

    • readString

      public String readString(int byteCount)
      Reads at max given number of bytes from the port, converting them to String using platform's default Charset. Returns immediately, without waiting for data to be available.
      Parameters:
      byteCount - maximum number of bytes that should be read
      Returns:
      all bytes that could be read as String, but no more than given byteCount.

    • readString

      public String readString(int byteCount, int timeout)
      Reads at max given number of bytes from the port, converting them to String using platform's default Charset. This operation blocks until given number of bytes is available to be read, the buffer of 64 KiB is full, or the given timeout is hit.
      Parameters:
      byteCount - maximum number of bytes that should be read.
      timeout - maximum time in milliseconds that we want to wait for all available bytes
      Returns:
      all bytes that could be read as String, but no more than given byteCount. When the timeout is hit, returns just bytes that were available.

    • readString

      public String readString(Charset charset)
      Read all available bytes from the port and converts them to String using given Charset. Returns immediately, without waiting for data to be available.
      Parameters:
      charset - Charset that will be used when converting bytes to String
      Returns:
      all bytes that could be read as String.

    • readString

      public String readString(Charset charset, int byteCount)
      Reads at max given number of bytes from the port, converting them to String using given Charset. Returns immediately, without waiting for data to be available.
      Parameters:
      charset - Charset that will be used when converting bytes to String
      byteCount - maximum number of bytes that should be read
      Returns:
      all bytes that could be read as String, but no more than given byteCount.

    • readString

      public String readString(Charset charset, int byteCount, int timeout)
      Reads at max given number of bytes from the port, converting them to String using given Charset. This operation blocks until given number of bytes is available to be read, the buffer of 64 KiB is full, or the given timeout is hit.
      Parameters:
      charset - Charset that will be used when converting bytes to String
      byteCount - maximum number of bytes that should be read.
      timeout - maximum time in milliseconds that we want to wait for all available bytes
      Returns:
      all bytes that could be read as String, but no more than given byteCount. When the timeout is hit, returns just bytes that were available.

    • invokeOperations

      public boolean invokeOperations(SolOperation... operations)
      Invokes given SOL-specific operations on remote serial port. SolOperation.Break, SolOperation.FlushInbound and SolOperation.FlushOutbound act once; SolOperation.CTS, SolOperation.DCD_DSR and SolOperation.RingWOR are line states, which the console holds in every packet it sends until the next call: call this method without them to release them.
      Parameters:
      operations - a bunch of SolOperations that should be invoked
      Returns:
      true if the packet was sent (its acknowledgement is not awaited: many BMCs never acknowledge a packet without characters), false otherwise.

    • registerEventListener

      public void registerEventListener(SolEventListener listener)
      Registers new SolEventListener that will be informed about SOL events fired by remote system.
      Parameters:
      listener - listener to be registered

    • unregisterEventListener

      public void unregisterEventListener(SolEventListener listener)
      Unregister given SolEventListener, preventing it from receiving SOL events from remote server.
      Parameters:
      listener - listener to be unregistered

    • close

      public void close() throws IOException
      Deactivates the SOL payload, closes the sessions the console opened, and tears down the connector when the console owns it: these are released even when the deactivation fails.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IOException - when the BMC does not confirm the deactivation