Package com.microsoft.jenkins.containeragents.remote

Class SSHClient

java.lang.Object
com.microsoft.jenkins.containeragents.remote.SSHClient
All Implemented Interfaces:
AutoCloseable
public class SSHClient extends Object implements AutoCloseable
An SSH client used to interact with a remote SSH server.

  • Constructor Details

    • SSHClient

      public SSHClient(String host, int port, String username, String password) throws com.jcraft.jsch.JSchException
      Throws:
      com.jcraft.jsch.JSchException

    • SSHClient

      public SSHClient(String host, int port, String username, Secret passPhrase, String... privateKeys) throws com.jcraft.jsch.JSchException
      Throws:
      com.jcraft.jsch.JSchException

    • SSHClient

      public SSHClient(String host, int port, com.cloudbees.plugins.credentials.common.StandardUsernameCredentials credentials) throws com.jcraft.jsch.JSchException
      Throws:
      com.jcraft.jsch.JSchException

    • SSHClient

      public SSHClient(String host, int port, com.microsoft.jenkins.containeragents.remote.UsernameAuth auth) throws com.jcraft.jsch.JSchException
      SSH client to the remote host with given credentials.

      The credentials can be one of the two:

      • UsernamePrivateKeyAuth with username and SSH private key.
      • Implementation of UsernamePasswordAuth with username and password.
      Parameters:
      host - the SSH server name or IP address.
      port - the SSH service port.
      auth - the SSH authentication credentials.
      Throws:
      com.jcraft.jsch.JSchException - if the passed in parameters are not valid, e.g., null username

  • Method Details

    • withLogger

      public SSHClient withLogger(PrintStream log)
      Set the optional logger stream to print the status messages.
      Parameters:
      log - the logger stream
      Returns:
      the current SSH client with the logger stream updated.

    • connect

      public SSHClient connect() throws com.jcraft.jsch.JSchException
      Establish a connection with the SSH server.

      Remember to close() the client after a session is established and it's no longer used. You may use the try with resource statement block. 

      
 try (SSHClient connected = notConnected.connect()) {
     // do things with the connected instance
 }

      This method can be called again if the the current session is closed. Otherwise if called on a connected instance, a JSchException will be thrown.

      Returns:
      the current instance so it can be used in try with resource block.
      Throws:
      com.jcraft.jsch.JSchException - if the client is already connected or error occurs during the connection.

    • copyTo

      public void copyTo(File sourceFile, String remotePath) throws com.jcraft.jsch.JSchException
      Copy local file to the remote path.
      Parameters:
      sourceFile - the local file.
      remotePath - the target remote path, can be either absolute or relative to the user home.
      Throws:
      com.jcraft.jsch.JSchException - if the underlying SSH session fails.

    • copyTo

      public void copyTo(InputStream in, String remotePath) throws com.jcraft.jsch.JSchException
      Copy the contents from the InputStream to the remote path.
      Parameters:
      in - the InputStream containing source contents.
      remotePath - the target remote path, can be either absolute or relative to the user home.
      Throws:
      com.jcraft.jsch.JSchException - if the underlying SSH session fails.

    • copyFrom

      public void copyFrom(String remotePath, File destFile) throws com.jcraft.jsch.JSchException
      Copy remote file to the local destination.
      Parameters:
      remotePath - the remote file path, can be either absolute or relative to the user home.
      destFile - the local destination file path.
      Throws:
      com.jcraft.jsch.JSchException - if the underlying SSH session fails.

    • copyFrom

      public void copyFrom(String remotePath, OutputStream out) throws com.jcraft.jsch.JSchException
      Copy remote file contents to the OutputStream.
      Parameters:
      remotePath - the remote file path, can be either absolute or relative to the user home.
      out - the OutputStream where the file contents should be written to.
      Throws:
      com.jcraft.jsch.JSchException - if the underlying SSH session fails.

    • withChannelSftp

      protected void withChannelSftp(com.microsoft.jenkins.containeragents.remote.SSHClient.ChannelSftpConsumer consumer) throws com.jcraft.jsch.JSchException
      Throws:
      com.jcraft.jsch.JSchException

    • execRemote

      public String execRemote(String command) throws com.jcraft.jsch.JSchException, IOException, SSHClient.ExitStatusException
      Execute a command on the remote server and return the command standard output.
      Parameters:
      command - the command to be executed.
      Returns:
      the standard output of the command.
      Throws:
      com.jcraft.jsch.JSchException - if the underlying SSH session fails.
      IOException - if it fails to read the output from the remote channel.
      SSHClient.ExitStatusException

    • execRemote

      public String execRemote(String command, boolean showCommand, boolean capture) throws com.jcraft.jsch.JSchException, IOException, SSHClient.ExitStatusException
      Throws:
      com.jcraft.jsch.JSchException
      IOException
      SSHClient.ExitStatusException

    • forwardSSH

      public SSHClient forwardSSH(String remoteHost, int remotePort) throws com.jcraft.jsch.JSchException
      Forward another remote SSH port to local through the current client, and create a new client based on the local port.

      This method assumes that the SSH server on A and B accepts the same authentication credentials.

      Parameters:
      remoteHost - the target host name or IP address, which is accessible from the SSH target of the current SSHClient.
      remotePort - the SSH service port on the target host.
      Returns:
      A new SSH client to the target host through the current SSH client.
      Throws:
      com.jcraft.jsch.JSchException - if error occurs during the SSH operations.

    • forwardSSH

      public SSHClient forwardSSH(String remoteHost, int remotePort, com.microsoft.jenkins.containeragents.remote.UsernameAuth sshCredentials) throws com.jcraft.jsch.JSchException
      Forward another remote SSH port to local through the current client, and create a new client based on the local port.

      Consider in the case with 2 or more remote severs, where:

      • We can connect to host A via SSH
      • We want to connect to host B but B is not publicly accessible.
      • A and B are in the same subnet so A can connect to B via SSH.

      We can first establish an SSH connection to host A, and then use the port forwarding to forward the connection to the local port through the SSH connection of host A to reach the SSH server on host B. 

      
     SSHClient connectionToA = new SSHClient(host_A, port_A, credentials_A);
     SSHClient tunnelConnectionToB = connectionToA.forwardSSH(host_B, port_B, credentials_B);
     tunnelConnectionToB.execRemote("ls"); // ls executed on host B
      Parameters:
      remoteHost - the target host name or IP address, which is accessible from the SSH target of the current SSHClient.
      remotePort - the SSH service port on the target host.
      sshCredentials - SSH authentication credentials
      Returns:
      A new SSH client to the target host through the current SSH client.
      Throws:
      com.jcraft.jsch.JSchException - if error occurs during the SSH operations.

    • getHost

      public String getHost()

    • getPort

      public int getPort()

    • getUsername

      public String getUsername()

    • getCredentials

      public com.microsoft.jenkins.containeragents.remote.UsernameAuth getCredentials()

    • close

      public void close()
      Specified by:
      close in interface AutoCloseable