Package com.microsoft.jenkins.azurecommons.remote

Class SSHClient

  • All Implemented Interfaces:
    AutoCloseable
    public class SSHClient
extends Object
implements AutoCloseable
    An SSH client used to interact with a remote SSH server.

    • Constructor Detail

      • 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.azurecommons.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 Detail

      • 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.azurecommons.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

      • 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.azurecommons.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.azurecommons.remote.UsernameAuth getCredentials()