com.sshtools.ssh

Class SshConnector

java.lang.Object

com.sshtools.ssh.SshConnector

public final class SshConnector
extends Object

This utility class establishes a connection with an SSH server, determines which SSH protocol versions are supported and creates an initialized connection ready for authentication.

Each call to createInstance() returns a new instance of the connector with a configuration context. These are designed to be re-used for many connections where the same configuration can be used.

To connect to an SSH server you need to provide an SshTransport which provides the transport layer communication. In most cases this will be a Socket however since this API is designed for many different platforms, a Socket may not always be available so this simple interface is used to allow you to specify the source IO streams. The SshTransport documentation provides a simple example for a Socket called SocketTransport which is used in the following examples.

To create a connection and authentication using password authentication with default configuration contexts use:

 SshConnector con = SshConnector.createInstance();
 SshClient ssh = con.connect(new SocketTransport("beagle2.sshtools.net", 22),
                "martianx");
 
 PasswordAuthentication pwd = new PasswordAuthentication();
 pwd.setPassword("likeidgivethataway!");
 
 if (ssh.authenticate(pwd) == SshAuthentication.COMPLETE) {
        System.out.println("Authentication succeeded");
        SshSession sesison = ssh.openSessionChannel();
 } else {
        System.out.println("Authentication failed");
 }
 

Author:

Lee David Painter

Field Summary

Fields

Modifier and Type	Field and Description
static Throwable	initException

Method Summary

Methods

Modifier and Type	Method and Description
static void	addEventListener(EventListener listener)
static void	addEventListener(String threadPrefix, EventListener listener)
Ssh2Client	connect(SshTransport transport, String username) Create a new connection to an SSH server over the specified transport.
SshClient	connect(SshTransport transport, String username, boolean buffered) See connect(SshTransport, String) for full details.
Ssh2Client	connect(SshTransport transport, String username, boolean buffered, SshContext context) See connect(SshTransport, String) for full details.
SshClient	connect(SshTransport transport, String username, SshContext context) See connect(SshTransport, String) for full details.
static SshConnector	createInstance() Returns an instance of the SshConnector.
void	enableFIPSMode()
Ssh2Context	getContext() Get the configuration context.
String	getProduct()
static void	removeEventListener(String threadPrefix)
void	setProduct(String product)
void	setSoftwareVersionComments(String softwareComments) Set the software/version/comments field of the SSH identification string

Methods inherited from class java.lang.Object

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

Field Detail

initException

public static Throwable initException

Method Detail

createInstance

public static SshConnector createInstance()
                                   throws SshException

Returns an instance of the SshConnector. Each instance is initialized with a pair of default contexts.

Returns:

a new instance

Throws:

SshException

addEventListener

public static void addEventListener(EventListener listener)

addEventListener

public static void addEventListener(String threadPrefix,
                    EventListener listener)

removeEventListener

public static void removeEventListener(String threadPrefix)

enableFIPSMode

public final void enableFIPSMode()
                          throws SshException

Throws:

SshException

getContext

public Ssh2Context getContext()
                       throws SshException

Get the configuration context.

Returns:

the version context

Throws:

SshException

connect

public Ssh2Client connect(SshTransport transport,
                 String username)
                   throws SshException

Create a new connection to an SSH server over the specified transport. This method reads the remote servers identification and determines which protocol support is required. An SshClient instance is then created, initialized and returned. If both protocol versions are supported by the remote server the connector will always operate using SSH2.

The SshTransport interface is used here to allow different types of transport mechanisms. Typically this would be a Socket however since this API is targeted at all Java platforms a Socket cannot be used directly. See the SshTransport documentation for an example Socket implementation.

Parameters:

transport - the transport for the connection.

username - the name of the user connecting

Returns:

a connected SshClient instance ready for authentication.

Throws:

SshException

See Also:

Ssh2Client

connect

public SshClient connect(SshTransport transport,
                String username,
                boolean buffered)
                  throws SshException

See connect(SshTransport, String) for full details. This method optionally allows you to specify the buffered state of the connection. When the connection is buffered a background thread is started to act as a message pump; this has the benefit of routing data as soon as it arrives and helps in circumstances where you require a channel to fill up with data without calling its InputStream's read method. This also will enable the InputStreams available method to work as expected.

Parameters:

transport - SshTransport

username - String

buffered - boolean

Returns:

SshClient

Throws:

SshException

connect

public SshClient connect(SshTransport transport,
                String username,
                SshContext context)
                  throws SshException

See connect(SshTransport, String) for full details. This method optionally allows you to specify a context to use. Normally you would reused an SshConnector instead of calling this method directly.

Parameters:

transport - SshTransport

username - String

context - SshContext

Returns:

SshClient

Throws:

SshException

setSoftwareVersionComments

public void setSoftwareVersionComments(String softwareComments)

Set the software/version/comments field of the SSH identification string

Parameters:

softwareComments - String

connect

public Ssh2Client connect(SshTransport transport,
                 String username,
                 boolean buffered,
                 SshContext context)
                   throws SshException

See connect(SshTransport, String) for full details.

This method optionally allows you to specify the buffered state of the connection. When the connection is buffered a background thread is started to act as a message pump; this has the benefit of routing data as soon as it arrives and helps in circumstances where you require a channel to fill up with data without calling its InputStream's read method. This also will enable the InputStreams available method to work as expected.

This method also allows you to specify a context to use. Normally you would reuse an SshConnector instead of calling this method directly.

Parameters:

transport - SshTransport

username - String

buffered - boolean

context - SshContext

Returns:

SshClient

Throws:

SshException

getProduct

public String getProduct()

setProduct

public void setProduct(String product)