{"id":16538790,"url":"https://github.com/sbabcoc/remote-session","last_synced_at":"2025-10-28T14:31:13.194Z","repository":{"id":38015696,"uuid":"112164159","full_name":"sbabcoc/Remote-Session","owner":"sbabcoc","description":"Remote Session is a small collection of utility classes for interacting with remote systems via Secure Shell (SSH) protocol.","archived":false,"fork":false,"pushed_at":"2023-06-14T22:52:07.000Z","size":116,"stargazers_count":13,"open_issues_count":2,"forks_count":8,"subscribers_count":5,"default_branch":"master","last_synced_at":"2023-08-25T02:38:14.354Z","etag":null,"topics":["jsch","remote-execution","remote-shell","secure-file-upload","ssh-client"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sbabcoc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-11-27T07:43:57.000Z","updated_at":"2023-06-29T08:26:24.000Z","dependencies_parsed_at":"2023-02-18T21:01:03.344Z","dependency_job_id":null,"html_url":"https://github.com/sbabcoc/Remote-Session","commit_stats":null,"previous_names":[],"tags_count":19,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbabcoc%2FRemote-Session","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbabcoc%2FRemote-Session/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbabcoc%2FRemote-Session/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbabcoc%2FRemote-Session/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sbabcoc","download_url":"https://codeload.github.com/sbabcoc/Remote-Session/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219859478,"owners_count":16556036,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jsch","remote-execution","remote-shell","secure-file-upload","ssh-client"],"created_at":"2024-10-11T18:46:49.936Z","updated_at":"2025-10-28T14:31:13.187Z","avatar_url":"https://github.com/sbabcoc.png","language":"Java","readme":"[![Maven Central](https://img.shields.io/maven-central/v/com.nordstrom.tools/remote-session.svg)](https://mvnrepository.com/artifact/com.nordstrom.tools/remote-session)\r\n\r\n# REMOTE SESSION UTILITIES\r\n\r\n**Remote Session** is a small collection of utility classes for interacting with remote systems via Secure Shell (SSH) protocol. Built around the [JSch](http://www.jcraft.com/jsch/) library from _JCraft_, available functions include:\r\n\r\n* Secure file transfer\r\n* Remote interactive shell\r\n* Remote command execution\r\n\r\n**Remote Session** wraps the capabilities of **JSch** in a simplified API that handles many of the details related to setting up and managing remote sessions. Originated by [Mykhaylo Adamovych](http://stackoverflow.com/users/448078/mykhaylo-adamovych), the implementation was copied verbatim from a post on [Stack Overflow](http://stackoverflow.com/questions/2405885/run-a-command-over-ssh-with-jsch). JavaDoc has been added for completeness and comprehensibility.\r\n\r\n## Continuing Development\r\n\r\nThe last release of the **JSch** library from the original [SourceForge project](https://sourceforge.net/projects/jsch/) was published 2018-NOV-26. Continuing development of this project has been taken up by **_Matthias Wiedemann_** [here](https://github.com/mwiede/jsch), with new releases published at these artifact coordinates:\r\n\r\n| Maven |\r\n|:---|\r\n| \u003cpre\u003e\u0026lt;dependency\u0026gt;\u003cbr/\u003e\u0026nbsp;\u0026nbsp;\u0026lt;groupId\u0026gt;com.github.mwiede\u0026lt;/groupId\u0026gt;\u003cbr/\u003e\u0026nbsp;\u0026nbsp;\u0026lt;artifactId\u0026gt;jsch\u0026lt;/artifactId\u0026gt;\u003cbr/\u003e\u0026nbsp;\u0026nbsp;\u0026lt;version\u0026gt;2.27.2\u0026lt;/version\u0026gt;\u003cbr/\u003e\u0026lt;/dependency\u0026gt;\u003c/pre\u003e |\r\n\r\n| Gradle |\r\n|:---|\r\n| \u003cpre\u003edependencies {\u003cbr/\u003e\u0026nbsp;\u0026nbsp;compile 'com.github.mwiede:jsch:2.27.2'\u003cbr/\u003e}\u003c/pre\u003e |\r\n\r\nThis new incarnation of the **JSch** project is a drop-in replacement for artifacts published from the original project. However, support for older or deprecated algorithms is disabled by default. Information on compatibility and configuration can be found on the project's [README](https://github.com/mwiede/jsch/blob/master/Readme.md#fork-of-jsch-0155) page. \r\n\r\n## Secure File Transfer\r\n\r\n**Remote Session** enables clients to upload and download files via secure file transfer protocol (SFTP).\r\n\r\n```java\r\n    SshUtils.sftp(\"file:/C:/home/file.txt\", \"ssh://user:pass@host/home\");\r\n    SshUtils.sftp(\"ssh://user:pass@host/home/file.txt\", \"file:/C:/home\");\r\n```\r\n\r\n**NOTE**: The transferred file retains its original name. If specified, the name component of `toUrl` will be ignored.  \r\n**NOTE**: As indicated by the examples, source and target URIs must refer to opposing locations: `file` for local file system and `ssh` for remote file system.\r\n\r\n* For upload: **fromUri** = `file`; **toUri** = `ssh`\r\n* For download: **fromUri** = `ssh`; **toUri** = `file`\r\n\r\n## Remote Interactive Shell\r\n\r\n**Remote Session** supports interacting with remote systems via a secure `shell` channel, in which input and output are streamed between local and remote systems. Each of the three methods provided for secure shell interaction exhibit different operational characteristics.\r\n\r\n###### Unbounded Stream I/O\r\n```java\r\nimport com.nordstrom.remote.SshUtils;\r\nimport java.io.InputStream;\r\nimport java.io.OutputStream;\r\nimport java.io.PrintStream;\r\nimport java.nio.charset.Charset;\r\nimport org.apache.commons.io.IOUtils;\r\n\r\n...\r\n\r\n    public void example() {\r\n        InputStream is = System.in;\r\n        OutputStream os = System.out;\r\n        SshUtils.shell(\"ssh://user:pass@host\", is, os);\r\n        PrintStream ps = new PrintStream(is, true);\r\n        ps.println(\"ls -la\");\r\n        ps.println(\"exit\");\r\n        System.out.println(IOUtils.toString(os, Charset.defaultCharset()));\r\n    }\r\n```\r\n\r\nWith unbounded stream I/O, the channel remains open until the input stream is closed or an `exit` command is submitted.\r\n\r\n###### Submit Specified Command\r\n```java\r\n    String remoteOutput = SshUtils.shell(\"ssh://user:pass@host/work/dir/path\", \"ls\");\r\n```\r\n\r\nFrom the client perspective, this is effectively equivalent to `exec(String, String)`. The primary difference is the channel used for communication (`shell` instead of `exec`).\r\n\r\n###### Submit Command with Streamed Output\r\n```java\r\nimport com.nordstrom.remote.SshUtils;\r\nimport java.io.OutputStream;\r\nimport java.nio.charset.Charset;\r\nimport org.apache.commons.io.IOUtils;\r\n\r\n...\r\n\r\n    public void example() {\r\n        OutputStream os = System.out;\r\n        SshUtils.shell(\"ssh://user:pass@host\", \"ls -la\", os);\r\n        System.out.println(IOUtils.toString(os, Charset.defaultCharset()));\r\n    }\r\n```\r\n\r\nThis is essentially a hybrid of the previous two secure-shell methods, well-suited for long-running commands that you'd like to leave running while you handle other tasks.\r\n\r\n## Remote Command Execution\r\n\r\n**Remote Session** enables you to submit commands to remote systems atomically. Instead of submitting commands through an input stream, you specify each command as a property of the channel and execute it.\r\n\r\n###### Execute Specified Command\r\n```java\r\n    System.out.println(SshUtils.exec(\"ssh://user:pass@host/work/dir/path\", \"ls -t | head -n1\"));\r\n```\r\n\r\n###### Execute Command \r\n```java\r\nimport java.net.URI;\r\nimport com.nordstrom.remote.SshUtils.SessionHolder;\r\nimport com.nordstrom.remote.SshUtils.ChannelType;\r\nimport com.jcraft.jsch.ChannelExec;\r\n\r\n...\r\n\r\n    public void example() {\r\n        String connectUri = \"ssh://user:pass@host/work/dir/path\";\r\n        String command = \"ls -t | head -n1\";\r\n        try (SessionHolder\u003cChannelExec\u003e session = new SessionHolder\u003c\u003e(ChannelType.EXEC, URI.create(connectUri))) {\r\n            String workDir = session.getWorkDir();\r\n            if (workDir != null) command = \"cd \" + workDir + \" \u0026\u0026 \" + command;\r\n            System.out.println(session, command);\r\n        }\r\n    }\r\n```\r\n\r\n## JSch Reference Implementation (BatchUtils)\r\n\r\n**BatchUtils** is a reference implementation of a **JSch** client. It enables you to execute the specified command, optionally executing an initial command to switch to an alternate user first.\r\n\r\n```java\r\n    String userName = \"user\";\r\n    String password = \"password\";\r\n    String hostName = \"host\";\r\n    String sudoCmd = \"sudo su - admin\";\r\n    String batchDir = \"/work/dir/path\";\r\n    String batchCmd = \"./script.ksh parm1 parm2\";\r\n    String output = BatchUtils.executeBatch(userName, password, hostName, sudoCmd, batchDir, batchCmd);\r\n    System.out.println(output);\r\n```\r\n\r\nThe implementation of `BatchUtils` demonstrates how to use a couple of important **Remote Session** classes:\r\n* `SessionHolder` - This is a wrapper class for objects that extend the `Channel` class. The wrapper implements the `Closeable` interface, and `BatchUtils` uses a \"try-with-resources\" block to ensure that the channel is always closed regardless of the outcome of command execution. `SessionHolder` includes these methods (among others):\r\n  * `getChannel` - Get the channel to the remote session created for this `SessionHolder`.\r\n  * `getChannelStream` - Get a new channel stream object for this session.\r\n  * `disconnect` - Disconnect channel and session.\r\n  * `assertExitStatus` - Verifies that the remote task completed normally.\r\n* `ChannelStreams` - This class encapsulates input/output operation for the channel attached to this session. It includes these methods:\r\n  * `waitForInput` - Wait for input to be available.\r\n  * `writeln` - Write the specified string to the remote host, followed by a carriage return.\r\n  * `waitForPrompt` - Wait for the specified prompt to be received from the remote host.\r\n  * `readChannel` - Read the input from the channel.\r\n  \r\n## **Remote Session** Settings\r\n\r\n**Remote Session** provides a number of important settings that can be configured through system properties or a corresponding `properties` file (_remote.properties_). The library provides default values for all settings in the **RemoteConfig** class.\r\n\r\n| Setting | Property Name | Default |\r\n| --- | --- |:---:|\r\n| **`SSH_KEY_NAME`** | `remote.ssh.key.name` | `id_rsa` |\r\n| **`SSH_KEY_PASS`** | `remote.ssh.key.pass` | _(none)_ |\r\n| **`IGNORE_KNOWN_HOSTS`** | `remote.ignore.known.hosts` | `false` |\r\n| **`SESSION_CONNECT_TIMEOUT`** | `remote.session.connect.timeout` | `5000` |\r\n| **`SSH_PORT_NUMBER`** | `remote.ssh.port.number` | `22` |\r\n| **`TERMINAL_HEIGHT`** | `remote.terminal.height` | `24` |\r\n| **`TERMINAL_WIDTH`** | `remote.terminal.width` | `132` |\r\n| **`TERMINAL_H_RESOLUTION`** | `remote.terminal.h.resolution` | `924` |\r\n| **`TERMINAL_V_RESOLUTION`** | `remote.terminal.v.resolution` | `216` |\r\n| **`COMPLETION_CHECK_INTERVAL`** | `remote.completion.check.interval` | `100` |\r\n| **`DISCONNECT_CHECK_ATTEMPTS`** | `remote.disconnect.check.attempts` | `600` |\r\n| **`DISCONNECT_CHECK_INTERVAL`** | `remote.disconnect.check.interval` | `100` |\r\n| **`CHANNEL_CHECK_INTERVAL`** | `remote.channel.check.interval` | `100` |\r\n| **`CHANNEL_BUFFER_SIZE`** | `remote.channel.buffer.size` | `102400` |\r\n\r\n### Setting Details\r\n\r\nThe **`SSH_KEY_NAME`** setting specifies the path to an SSH key file for authentication to the remote host. If the key file is specified by full path, this is used as-is. Otherwise, the key file must be located in the .ssh folder of the active user's HOME directory. If the key file is encrypted, you must provide the decryption passphrase in the **`SSH_KEY_PASS`** setting. This also implies the presence of a corresponding `pub` file in the same folder as the key file.\r\n\r\nIf a _known_hosts_ file is stored in the same folder as the SSH key file(s), this _known_hosts_ file will be supplied to **JSch** as your personal Certificate Authority. The **`IGNORE_KNOWN_HOSTS`** setting specifies that this _known_hosts_ file should be ignored.\r\n\r\n\u003e **NOTE**: If credentials are specified in the remote host URL, the `SSH_KEY_NAME` and `SSH_KEY_PASS` settings are ignored. Also, no attempt is made to locate a _known_hosts_ file for **JSch**.\r\n\r\nThe **`SESSION_CONNECT_TIMEOUT`** setting is the interval in milliseconds that **JSch** will wait for socket connection operations to complete. If this value is set to **`0`**, no timeout will be established.\r\n\r\nThe **`COMPLETION_CHECK_INTERVAL`** setting is the interval in milliseconds between END-OF-FILE checks for remote command execution.\r\n\r\nThe **`DISCONNECT_CHECK_INTERVAL`** setting in the interval in milliseconds between checks for the closure of the remote session channel.\r\n\r\nThe **`CHANNEL_CHECK_INTERVAL`** setting is the interval in millisecinds between checks for available input from the remote session channel.\r\n\r\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsbabcoc%2Fremote-session","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsbabcoc%2Fremote-session","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsbabcoc%2Fremote-session/lists"}