Introduction to SSHJ

1. Overview

SSHJ is an open-source Java library that uses SSH protocols for secure communication with remote servers.

In this article, we’ll go through the basic functionality of the SSHJ library.

2. Dependencies

To use the SSHJ library, we’ll have to add the following dependency to the project:

<dependency>
    <groupId>com.hierynomus</groupId>
    <artifactId>sshj</artifactId>
    <version>0.38.0</version>
</dependency>

We can find the latest version of the SSHJ library in Maven Central.

3. SSHJ Library

The SSHJ library helps establish secure connections to remote servers over SSH.

With the SSHJ library, we can handle file upload and download using SCP or SFTP protocols. Plus, we’ve got the added bonus of being able to do local port forwarding and remote port forwarding with it too.

4. Connecting SSH Client

SSH clients can connect to the server using password or public key authentication. The SSHJ library enables us to log in using either method.

4.1. Password Authentication

We can connect to a server via an SSH port using the SSHJ library. The hostname, port, username, and password need to be specified for the SSH connection.

The SSH client connects to the server via password authentication using the authPassword() method:

String host = // ...
int port = // ...
String username = // ...
String password = // ...

SSHClient client = new SSHClient();
client.addHostKeyVerifier(new PromiscuousVerifier());
client.connect(host, port);
client.authPassword(username, password);

As we can see in the above code, we connect the client to the host using password authentication.

4.2. Public Key Authentication

We can connect to the server using the public key as well. For connecting with the public key, we need to have a file entry in the known_hosts file on the server, or we can generate a public key for the remote server on the client machine and copy the public key into authorized SSH keys on the server.

The SSH client connects to the server via public key authentication using the authPublickey() method:

String host = // ... 
String username = // ... 
File privateKeyFile = // ... 
int port = // ...

SSHClient client = new SSHClient();
KeyProvider privateKey = client.loadKeys(privateKeyFile.getPath());
client.addHostKeyVerifier(new PromiscuousVerifier());
client.connect(host, port);
client.authPublickey(username, privateKey);

We can generate a public key for the client and update it on the server to be connected. In the rest of the examples, we’ll log in using the first method, i.e., using a username and password.

5. Executing a Command via SSH

We can execute commands via the SSHJ library using the exec() method on session started by the sshClient connected to the server:

SSHClient client = new SSHClient();
Session session = sshClient.startSession();
Command cmd = session.exec("ls -lsa");
BufferedReader reader = new BufferedReader(new InputStreamReader(cmd.getInputStream()));
String line;
while ((line = reader.readLine()) != null) {
    System.out.println(line);
}
cmd.join(5, TimeUnit.SECONDS);
session.close();

As we can see in the above code, we start a session for sshClient. Then, we execute the ls -lsa command, which lists all files in the directory. We’ve then used BufferedReader to read the output of the command executed.

Similarly, other commands can also be executed here.

6. Uploading/Downloading File via SCP

We can upload a file via SCP. For upload, we use the upload() method on SCPFileTransfer object:

String filePath = // ... 

SSHClient ssh = new SSHClient();
ssh.useCompression();
ssh.newSCPFileTransfer()
  .upload(new FileSystemFile(filePath), "/upload/");

Here, we transfer a file to the upload directory on the server.

The method useCompression() adds zlib compression to preferred algorithms, which can lead to significant speedups. There’s no guarantee it’ll be successfully negotiated. If the client is already connected, then renegotiation is done; otherwise, it simply returns. We can use useCompression() before connecting the client, too.

For SCP file download, we use the download() method on SCPFileTransfer object:

String downloadPath = // ...
String fileName = // ...

SSHClient ssh = new SSHClient();
ssh.useCompression();
ssh.newSCPFileTransfer()
  .download("/upload/" + fileName, downloadPath);

Here, we download the file from the upload directory on the server to the downloadPath location on the client.

The above upload and download methods run the scp command internally, copying files from the local machine to the remote server using an SSH connection and vice versa.

7. Uploading/Downloading File via SFTP

We can upload files via SFTP. For upload, we use the put() method on SFTPClient object:

String filePath = // ...

SSHClient ssh = new SSHClient();
SFTPClient sftp = ssh.newSFTPClient();
sftp.put(new FileSystemFile(filePath), "/upload/");

Here, we transfer the file from the user’s home directory on the client to the upload directory on the server.

For SFTP download, we use the get() method on SFTPClient object:

String downloadPath = // ...
String fileName = // ...

SSHClient ssh = new SSHClient();
SFTPClient sftp = ssh.newSFTPClient();
sftp.get("/upload/" + fileName, downloadPath);
sftp.close();

Here, we download the file from the upload directory on the server to the downloadPath location on the client.

8. Local Port Forwarding

Local port forwarding is used to access services on a remote server as if the services were running on a client:

SSHClient ssh = new SSHClient();
Parameters params = new Parameters(ssh.getRemoteHostname(), 8081, "google.com", 80);
ServerSocket ss = new ServerSocket();
ss.setReuseAddress(true);
ss.bind(new InetSocketAddress(params.getLocalHost(), params.getLocalPort()));
ssh.newLocalPortForwarder(params, ss)
  .listen();

Here, we forward port 80 of the server to port 8081 of the client machine so we can access the website or service hosted on server port 80 from port 8081 on the client machine.

9. Remote Port Forwarding

Using remote port forwarding, we can expose services running on client machines to the remote server network:

SSHClient ssh = new SSHClient();
ssh.getConnection()
  .getKeepAlive()
  .setKeepAliveInterval(5);
ssh.getRemotePortForwarder()
  .bind(new Forward(8083), new SocketForwardingConnectListener(new InetSocketAddress("google.com", 80)));
ssh.getTransport()
  .join();

Here, we forward the service running on the 8083 port of the client to port 80 of the remote server. Effectively, the service running on the client machine at the 8083 port is exposed on port 80 of the remote server.

For both local and remote port forwarding, we need to ensure that proper firewall settings are in place.

10. Check Connection Drops

We need to check connection drops to monitor server connection status and health. SSHJ provides the option of checking connection drops using keep alive:

String hostName = // ...
String userName = // ...
String password = // ...

DefaultConfig defaultConfig = new DefaultConfig();
defaultConfig.setKeepAliveProvider(KeepAliveProvider.KEEP_ALIVE);
SSHClient ssh = new SSHClient(defaultConfig);

ssh.addHostKeyVerifier(new PromiscuousVerifier());
ssh.connect(hostName, 22);
ssh.getConnection()
  .getKeepAlive()
  .setKeepAliveInterval(5);
ssh.authPassword(userName, password);

Session session = ssh.startSession();
session.allocateDefaultPTY();
new CountDownLatch(1).await();
session.allocateDefaultPTY();

session.close();
ssh.disconnect();

In the above code, we can see that the configuration KeepAliveProvider.KEEP_ALIVE enables the keep alive mode for the SSHJ library.

We used setKeepAliveInterval() to set the interval between two keep-alive messages from the client.

11. Conclusion

In this article, we reviewed the basic usage and implementations of the SSHJ library. We figured out how to upload or download files using SCP and SFTP modes. Plus, we saw how to connect the SSH client using a password or public key authentication. Remote and local port forwarding is also achievable via the SSHJ library. Overall, the SSHJ library does most of the things for an SSH client in Java.

As always, the source code examples are available over on GitHub.