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
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).
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.
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
creates the jar file (compiling the classes if necessary). There are also other interesting targets, use
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
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.
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
- 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
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.
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.)
- 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.
- Official examples in the distribution.
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.