Frequently Asked Questions

Installation

  1. What version of Java does SSHAPI work with?
  2. What Jars do I need to use the API?
  3. Can I use Maven with SSHAPI?

Providers

  1. How is the provider chosen at run time?
  2. How do I select a provider at run time?
  3. How do I hard-code a provider to use
  4. Can I use multiple providers at the same time?

General

  1. What Is Per-connection Configuration

Installation

What version of Java does SSHAPI work with?

The core library itself and the providers bridges will work currently on any version of Java from 1.2 and above. However, some providers themselves may have different requirements, or may have in the future. See the individual provider documentation for more information.

What Jars do I need to use the API?

You will need at least 3 Jar files to use SSHAPI, the first two .

  • The core API library, sshapi.jar . Unless you are directly using classes from one of the provider bridges or the provider itself, this is all that is required to be able to compile your application against this API.
  • At least one provider bridge library. For example, sshapi-ganymed.jar . This does not contain the provider itself.
  • Any Jars require for the provider itself. This may be a single Jar, or multiple libraries. Some providers may offer additional functionality when additional libraries are added.

Check the individual module documentation for information on the provider versions currently supported.

Can I use Maven with SSHAPI?

Yes! SSHAPI is developed using Maven, and there is a repository host in Sourceforge's SVN that contains the API core and provider bridge libraries. The provider implementations are hosted there, but any libraries required by the providers are not, so these must be pulled from either the central repository, or installed your own local repository.

To use the Sourceforge repository, add the following to your POM :- 

<repositories>
  ..
    <repository>
      <id>sshtools</id>
 	  <url>
 	    http://svn.code.sf.net/p/sshapi/svn/sshapi-mvn/releases
 	  </url>
	  <releases />
	  <snapshots>
	    <enabled>false</enabled>
	  </snapshots>
    </repository>
  ..
</repositories>

Then add at least one of the provider bridge libraries to your dependencies.

..
<dependency>
  <groupId>net.sf.sshapi</groupId>
  <artifactId>sshapi-ganymed</artifactId>
  <version>0.9.5</version>
</dependency>
..

You can just add the API core to your project, which will allow you to compile your project, but the provider bridge libraries and provider implementations will have to be added to your CLASSPATH at runtime.

..
<dependency>
  <groupId>net.sf.sshapi</groupId>
  <artifactId>sshapi</artifactId>
  <version>0.9.5</version>
</dependency>
..

Providers

How is the provider chosen at run time?

One of the goals of SSHAPI is to make this is simple and flexible as possible. For normal use, you simply use DefaultProviderFactory whenever you want to create a new client connection :- 

SshConfiguration configuration = new SshConfiguration();
SshProvider provider = 
      DefaultProviderFactory.getInstance().createProvider(configuration);
SshClient client = provider.createClient(configuration);
client.connect("me", "localhost", 22);

DefaultProviderFactory will then search all available providers for one that supports the provided configuration and return the first one it finds (unless override by a system property, see below).

Once created, you may use a provider instance to create as many client instances as you wish.

How do I select a provider at run time?

You may wish to allow you user to chose the provider at runtime. To do this, simple set the system property net.sf.sshapi.provider to be the class name of the provider bridge implementation. For example, to select Jsch , you would invoke java with the following options :- 

java -Dnet.sf.sshapi.provider=net.sf.sshapi.jsch.JschSshProvider \
    com.mycompany.myapp.MyApp

This then forces DefaultProviderFactory to always return an instance of this provider, throwing an exception if the provider is not available or cannot be used with the supplied configuration.

How do I hard-code a provider to use

While this is not really recommended, you can simply not use DefaultClientFactory and instantiate the provider directly :- 

SshConfiguration configuration = new SshConfiguration();
SshProvider provider = new MaverickSshProvider();
SshClient client =
provider.createClient(configuration);
client.connect("me", "localhost", 22);
Can I use multiple providers at the same time?

Yes, simply avoid using DefaultProviderFactory and create all the providers you wish. 

SshConfiguration configuration = new SshConfiguration();
SshProvider maverickProvider = new MaverickSshProvider();
SshProvider jschProvider = new JschSshProvider();
SshClient mavClient = maverickProvider.createClient(configuration);
SshClient jschClient = jschProvider.createClient(configuration);
mavClient.connect("me", "localhost", 22);
jschClient.connect("me", "localhost", 22);

General

What Is Per-connection Configuration

SSHAPI tries to allow as much configuration as possible to be at the Connection level. However, an implementation may only support Global configuration for some items. For example, the preferred cipher may only be selectable globally.

In practice, currently only JSch has some configuration that may only be globally set. If you try and create a second client when using this provider, a warning message will be displayed on the console. You may also query the provider to see if it supports this capability. 

SshConfiguration configuration = new SshConfiguration();
SshProvider provider =
DefaultProviderFactory.getInstance().createProvider(configuration);
SshClient client = provider.createClient(configuration);

// Do something with client1

// Create a 2nd client
if(provider.getCapabilities().contains(
	Capability.PER_CONNECTION_CONFIGURATION)) {
	SshConfiguration configuration2 = new SshConfiguration();
	SshClient client2 = provider.createClient(configuration2);
	
	// Do something with client2
}