Package org.sentrysoftware.ssh

Class SshClient

java.lang.Object
org.sentrysoftware.ssh.SshClient
All Implemented Interfaces:
AutoCloseable
public class SshClient extends Object implements AutoCloseable
SSH Client that lets you perform basic SSH operations
  1. Instantiate the SSH Client
  2. Connect
  3. Authenticate
  4. Enjoy!
  5. DISCONNECT!
Author:
Bertrand

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    SshClient.CommandResult
    Represents the result of a command execution

  • Constructor Summary

    Constructors
    Constructor
    Description
    SshClient(String pHostname)
    Creates an SSHClient to connect to the specified hostname
    SshClient(String pHostname, String pLocale)
    Creates an SSHClient to connect to the specified hostname
    SshClient(String pHostname, Charset pCharset)
    Creates an SSHClient to connect to the specified hostname

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    authenticate(String username)
    Authenticate the SSH Client against the SSH server using NO password
    boolean
    authenticate(String username, char[] password)
    Authenticate the SSH Client against the SSH server using a password
    boolean
    authenticate(String username, File privateKeyFile, char[] password)
    Authenticate the SSH Client against the SSH server using a private key
    boolean
    authenticate(String username, String password)
    Deprecated.
    (since = "3.14.00", forRemoval = true)
    boolean
    authenticate(String username, String privateKeyFile, String password)
    Deprecated.
    (since = "3.14.00", forRemoval = true)
    void
    checkIfSessionOpened()
    Check if the SSH session exists.
    void
    close()
    Disconnects the SSH Client from the SSH server
    void
    connect()
    Connects the SSH Client to the SSH server
    void
    connect(int timeout)
    Connects the SSH client to the SSH server using the default SSH port (22).
    void
    connect(int timeout, int port)
    Connects the SSH client to the SSH server using a specified SSH port.
    void
    disconnect()
    Deprecated.
    (since = "3.14.00", forRemoval = true)
    SshClient.CommandResult
    executeCommand(String command)
    Executes a command through the SSH connection
    SshClient.CommandResult
    executeCommand(String command, int timeout)
    Executes a command through the SSH connection
    void
    interactiveSession(InputStream in, OutputStream out)
    Starts an interactive session.
    String
    listFiles(String remoteDirectoryPath, String regExpFileMask, boolean includeSubfolders)
    List the content of the specified directory through the SSH connection (using SCP)
    void
    openSession()
    Open a SSH Session.
    void
    openTerminal()
    Open a Terminal request for a wiiiiide terminal, with no ECHO (see https://tools.ietf.org/html/rfc4254#section-8)
    Optional<String>
    read(int size, int timeout)
    Read the stdout and stderr from the SSH session.
    String
    readFile(String remoteFilePath, Long readOffset, Integer readSize)
    Read the specified file over the SSH session that was established.
    String
    readFileAttributes(String filePath)
    Return information about the specified file on the connected system, in the same format as the PSL function file()
    void
    removeFile(String remoteFilePath)
    Removes the specified file on the remote system.
    void
    removeFile(String[] remoteFilePathArray)
    Removes a list of files on the remote system.
    void
    scp(String localFilePath, String remoteFilename, String remoteDirectory, String fileMode)
    Copy a file to the remote host through SCP
    void
    write(String text)
    Write into the SSH session.

    Methods inherited from class java.lang.Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • SshClient

      public SshClient(String pHostname)
      Creates an SSHClient to connect to the specified hostname
      Parameters:
      pHostname - Hostname of the SSH server to connect to

    • SshClient

      public SshClient(String pHostname, String pLocale)
      Creates an SSHClient to connect to the specified hostname
      Parameters:
      pHostname - Hostname of the SSH server to connect to
      pLocale - Locale used on the remote server (e.g. zh_CN.utf8)

    • SshClient

      public SshClient(String pHostname, Charset pCharset)
      Creates an SSHClient to connect to the specified hostname
      Parameters:
      pHostname - Hostname of the SSH server to connect to
      pCharset - Charset used on the remote server

  • Method Details

    • connect

      public void connect() throws IOException
      Connects the SSH Client to the SSH server
      Throws:
      IOException

    • connect

      public void connect(int timeout) throws IOException
      Connects the SSH client to the SSH server using the default SSH port (22).
      Parameters:
      timeout - Timeout in milliseconds
      Throws:
      IOException - when connection fails or when the server does not respond (SocketTimeoutException)

    • connect

      public void connect(int timeout, int port) throws IOException
      Connects the SSH client to the SSH server using a specified SSH port.
      Parameters:
      timeout - Timeout in milliseconds
      port - SSH server port.
      Throws:
      IOException - when connection fails or when the server does not respond (SocketTimeoutException)

    • disconnect

      @Deprecated public void disconnect()
      Deprecated.
      (since = "3.14.00", forRemoval = true)
      Disconnects the SSH Client from the SSH server

      Note: This is important! Otherwise, the listener thread will remain running forever! Use a try with resource instead or the close() instead.

    • close

      public void close()
      Disconnects the SSH Client from the SSH server

      Note: This is important! Otherwise, the listener thread will remain running forever!

      Specified by:
      close in interface AutoCloseable

    • authenticate

      @Deprecated public boolean authenticate(String username, String privateKeyFile, String password) throws IOException
      Deprecated.
      (since = "3.14.00", forRemoval = true)
      Authenticate the SSH Client against the SSH server using a private key
      Parameters:
      username -
      privateKeyFile -
      password -
      Returns:
      a boolean stating whether the authentication worked or not
      Throws:
      IOException

    • authenticate

      public boolean authenticate(String username, File privateKeyFile, char[] password) throws IOException
      Authenticate the SSH Client against the SSH server using a private key
      Parameters:
      username -
      privateKeyFile -
      password -
      Returns:
      a boolean stating whether the authentication worked or not
      Throws:
      IOException

    • authenticate

      @Deprecated public boolean authenticate(String username, String password) throws IOException
      Deprecated.
      (since = "3.14.00", forRemoval = true)
      Authenticate the SSH Client against the SSH server using a password
      Parameters:
      username -
      password -
      Returns:
      a boolean stating whether the authentication worked or not
      Throws:
      IOException

    • authenticate

      public boolean authenticate(String username, char[] password) throws IOException
      Authenticate the SSH Client against the SSH server using a password
      Parameters:
      username -
      password -
      Returns:
      a boolean stating whether the authentication worked or not
      Throws:
      IOException

    • authenticate

      public boolean authenticate(String username) throws IOException
      Authenticate the SSH Client against the SSH server using NO password
      Parameters:
      username -
      Returns:
      a boolean stating whether the authentication worked or not
      Throws:
      IOException

    • readFileAttributes

      public String readFileAttributes(String filePath) throws IOException
      Return information about the specified file on the connected system, in the same format as the PSL function file()
      Parameters:
      filePath - Path to the file on the remote system
      Throws:
      IOException

    • listFiles

      public String listFiles(String remoteDirectoryPath, String regExpFileMask, boolean includeSubfolders) throws IOException
      List the content of the specified directory through the SSH connection (using SCP)
      Parameters:
      remoteDirectoryPath - The path to the directory to list on the remote host
      regExpFileMask - A regular expression that listed files must match with to be listed
      includeSubfolders - Whether to parse subdirectories as well
      Returns:
      The list of files in the specified directory, separated by end-of-lines
      Throws:
      IOException - When something bad happens while communicating with the remote host
      IllegalStateException - If called while not yet connected

    • readFile

      public String readFile(String remoteFilePath, Long readOffset, Integer readSize) throws IOException
      Read the specified file over the SSH session that was established.
      Parameters:
      remoteFilePath - Path to the file to be read on the remote host
      readOffset - Offset to read from
      readSize - Amount of bytes to be read
      Returns:
      The content of the file read
      Throws:
      IOException - when something gets wrong while reading the file (we get disconnected, for example, or we couldn't read the file)
      IllegalStateException - when the session hasn't been properly authenticated first

    • removeFile

      public void removeFile(String[] remoteFilePathArray) throws IOException
      Removes a list of files on the remote system.
      Parameters:
      remoteFilePathArray - Array of paths to the files to be deleted on the remote host
      Throws:
      IOException - when something bad happens while deleting the file
      IllegalStateException - when not connected and authenticated yet

    • removeFile

      public void removeFile(String remoteFilePath) throws IOException
      Removes the specified file on the remote system.
      Parameters:
      remoteFilePath -
      Throws:
      IOException
      IllegalStateException

    • executeCommand

      public SshClient.CommandResult executeCommand(String command) throws IOException
      Executes a command through the SSH connection
      Parameters:
      command - The command to be executed
      Returns:
      a CommandResult object with the result of the execution
      Throws:
      IllegalStateException - when the connection is not established first
      IOException - when there is a problem while communicating with the remote system

    • executeCommand

      public SshClient.CommandResult executeCommand(String command, int timeout) throws IOException
      Executes a command through the SSH connection
      Parameters:
      command - The command to be executed
      timeout - Milliseconds after which the command is considered failed
      Returns:
      a CommandResult object with the result of the execution
      Throws:
      IllegalStateException - when the connection is not established first
      IOException - when there is a problem while communicating with the remote system

    • interactiveSession

      public void interactiveSession(InputStream in, OutputStream out) throws IOException, InterruptedException
      Starts an interactive session.
      Parameters:
      in - Where the input is coming from (typically System.in)
      out - Where the output has to go (e.g. System.out)
      Throws:
      IllegalStateException - when not connected and authenticated
      IOException - in case of communication problems with the host
      InterruptedException - when a thread is interrupted

    • scp

      public void scp(String localFilePath, String remoteFilename, String remoteDirectory, String fileMode) throws IOException
      Copy a file to the remote host through SCP
      Parameters:
      localFilePath -
      remoteFilename -
      remoteDirectory -
      fileMode -
      Throws:
      IOException

    • openSession

      public void openSession() throws IOException
      Open a SSH Session.
      Throws:
      IOException - When an I/O error occurred.

    • openTerminal

      public void openTerminal() throws IOException
      Open a Terminal request for a wiiiiide terminal, with no ECHO (see https://tools.ietf.org/html/rfc4254#section-8)
      Throws:
      IOException - When an I/O error occurred.

    • write

      public void write(String text) throws IOException
      Write into the SSH session.
      Parameters:
      text - The text to be written.
      Throws:
      IOException - When an I/O error occurred.

    • read

      public Optional<String> read(int size, int timeout) throws IOException
      Read the stdout and stderr from the SSH session.
      Parameters:
      size - The buffer size of stdout and/or stderr to be read. (If less than 0 all data)
      timeout - Timeout in seconds
      Returns:
      An optional with all the data read (stdout and stderr). Empty if nothing was read.
      Throws:
      IOException - When an I/O error occurred.

    • checkIfSessionOpened

      public void checkIfSessionOpened()
      Check if the SSH session exists.