Manual

From jsch

Contents 1 Introduction 2 Developing applications with JSch 2.1 Getting JSch 2.2 System/library requirements 2.3 Compiling and running your application with JSch 2.4 Building JSch and examples 2.5 Platform specific issues 3 Javadoc Documentation 4 Using JSch 4.1 Connecting to the remote server 4.2 Authentication methods 4.3 Channels 4.4 Extended use 4.5 Examples 5 License 6 Feedback and Troubleshooting

Introduction

JSch (Java Secure Channel) is a pure Java implementation of the client side of the SSH 2 protocol, in the form of a library.

JSch allows your Java application to connect to an sshd server and use port forwarding, X11 forwarding, file transfer, etc. (The example programs allow doing this also without programming your own application.)

JSch is licensed under a BSD style license.

Developing applications with JSch

Getting JSch

To start developing with JSch, you can obtain the library in one of these ways:

• use some project or dependency manager which automatically downloads it (like Maven, Ivy, ...)
• use some OS distribution which contains the library jar (maybe installing it with your package manager).
• use some software which already contains it (for example, if you are developing plugins for it)
• download the library as jar file or source zip from the official home page. In the source variant, you'll have to compile it yourself, see below.
• get the inofficial documented source from Paŭlo on Github (by git or as a zipball/tarball - use the download button).

System/library requirements

To use JSch (or applications built with JSch), you need the following:

• Java runtime environment (JRE) - a JDK if you want to build your own application or compile JSch from source
  • J2SE 1.2.2 or later (but see next point)
• Java Cryptography Extension (JCE). This will be used for the cryptographic algorithms. (You could alternatively plug in your own implementations, see Extending JSch.)
  • Bouncy Castle offers a free implementation with additional algorithms. (You might need this when running on non-J2SE Java environments like Blackberry.)
  • for J2SE 1.3.0, Sun offered the reference implementation as a download (I can't find this now).
  • from J2SE 1.4.0, the reference implementation is included in the Sun (and OpenJDK) JREs.
• For compression support: JZlib available in the runtime class path.
• For X forwarding: an X server accepting connections per TCP.
  • If you are on a non-X windowing system like Microsoft Windows, you might try a Java X server implementation like WiredX (commercial) or WeirdX (GPL) (both from the same author as JSch).

Compiling and running your application with JSch

• For compiling your application, make sure the JSch jar is available in the compiler class path. (In javac, use -classpath for this.)
• On runtime, make sure the JSch classes are available by some class loader which is a parent of the class loader of the classes using the library.
  • In most simple cases it is sufficient to put the jar file on the runtime class path.
  • If you extend JSch by putting in new implementation classes, these extension classes must be loaded by the same class loader as JSch itself.

Building JSch and examples

The most easy way to build JSch is using ant and the build.xml included in the source. The command

ant dist

creates the jar file (compiling the classes if necessary). There are also other interesting targets, use

ant -projecthelp

for a list.

There are also build.sh and build.bat scripts which assume you have an ant installation in the tools subdirectory. (I did not try them.)

Platform specific issues

(TODO)

Javadoc Documentation

A version created by Paŭlo Ebermann: Docs for JSch 0.1.44 (only important classes/interfaces), (complete version)

This Manual links to classes/interfaces in the simple version where necessary.

Using JSch

Connecting to the remote server

In principle, you create a Session indicating user and hostname (maybe port), set some options regarding authentication, and then call connect().

• Using a proxy or a socket factory - if you can't reach the remote server directly
• Using a host key repository - how to make sure the remote server is who it claims to be

Authentication methods

After connecting, most servers will require some authentication before anything useful can happen. Conceptually, you authenticate as some user account of the remote system, and many SSH server implementations map the authentication to the native OS user accounts. Partly they can be enabled by existence of some files in user's directories.

JSch supports most authentication methods defined in the SSH 2 protocol, and allows applications to plug in more methods. JSch tries the authentication methods in the order given by the configuration option PreferredAuthentications, if they are supported by the server.

• Password authentication
• Public key authentication
• Keyboard-interactive authentication
• GSS-API authentication
• Partial authentication
• Host-based authentication is not supported out-of-the-box (as this is normally not really useful in the use cases of an embedded library like JSch), but there could be created a plugin supporting this, I think.

Channels

After connecting and authenticating, you usually will want to do something on the remote server. The SSH 2 protocol allows multiplexing multiple "channels" of same or different type over the connection. All channels provide some similar basic functionality, given in the Channel class, namely input and output forwarding from/to some process at the remote side.

But each Channel type has also its additional considerations, and some must be configured before connecting.

• Shell, Exec or Subsystem Channel - executing a remote shell, command or server subsystem, and interacting with it.
• Sftp Channel - browsing the remote file system, uploading/downloading remote files.
• Direct or Forwarded TCPIP Channel - connecting to another host at the remote side, or handling connections from another host at the remote side. (Also, port forwardings.)

Extended use

• Configuration options - change the default behavior.
• Logging - see what happens behind the scene.
• Extending JSch - if you want to do something which is not possible out of the box.

Examples

• Official examples in the distribution.

• SwingDialogUserInfo - user interaction.
• ProxySSH - tunneling SSH over SSH.

License

Copyright (c) 2002,2003,2004 Atsuhiko Yamanaka, JCraft,Inc. 
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice,
     this list of conditions and the following disclaimer.

  2. Redistributions in binary form must reproduce the above copyright 
     notice, this list of conditions and the following disclaimer in 
     the documentation and/or other materials provided with the distribution.

  3. The names of the authors may not be used to endorse or promote products
     derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED ``AS IS AND ANY EXPRESSED OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JCRAFT,
INC. OR ANY CONTRIBUTORS TO THIS SOFTWARE BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Feedback and Troubleshooting