com.microsoft.jenkins.azurecommons.remote

Class SSHClient

java.lang.Object

com.microsoft.jenkins.azurecommons.remote.SSHClient

All Implemented Interfaces:

AutoCloseable

public class SSHClient
extends Object
implements AutoCloseable

An SSH client used to interact with a remote SSH server.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SSHClient.ExitStatusException

Constructor Summary

Constructors

Constructor and Description
SSHClient(String host, int port, com.cloudbees.plugins.credentials.common.StandardUsernameCredentials credentials)
SSHClient(String host, int port, String username, hudson.util.Secret passPhrase, String... privateKeys)
SSHClient(String host, int port, String username, String password)
SSHClient(String host, int port, com.microsoft.jenkins.azurecommons.remote.UsernameAuth auth) SSH client to the remote host with given credentials.

Method Summary

Modifier and Type	Method and Description
void	close()
SSHClient	connect() Establish a connection with the SSH server.
void	copyFrom(String remotePath, File destFile) Copy remote file to the local destination.
void	copyFrom(String remotePath, OutputStream out) Copy remote file contents to the OutputStream.
void	copyTo(File sourceFile, String remotePath) Copy local file to the remote path.
void	copyTo(InputStream in, String remotePath) Copy the contents from the InputStream to the remote path.
String	execRemote(String command) Execute a command on the remote server and return the command standard output.
String	execRemote(String command, boolean showCommand, boolean capture)
SSHClient	forwardSSH(String remoteHost, int remotePort) Forward another remote SSH port to local through the current client, and create a new client based on the local port.
SSHClient	forwardSSH(String remoteHost, int remotePort, com.microsoft.jenkins.azurecommons.remote.UsernameAuth sshCredentials) Forward another remote SSH port to local through the current client, and create a new client based on the local port.
com.microsoft.jenkins.azurecommons.remote.UsernameAuth	getCredentials()
String	getHost()
int	getPort()
String	getUsername()
protected void	withChannelSftp(com.microsoft.jenkins.azurecommons.remote.SSHClient.ChannelSftpConsumer consumer)
SSHClient	withLogger(PrintStream log) Set the optional logger stream to print the status messages.

Methods inherited from class java.lang.Object

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

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,
                 hudson.util.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

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.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()

close

public void close()

Specified by:

close in interface AutoCloseable