HiveSsh is an innovative library designed to streamline SSH2 connections and simplify task execution on Linux servers.
It wraps around the ssh2-library, providing a promise-based approach to avoid nested callbacks and adding useful features such as command existence checking and persistent exec sessions.
The term ssh2 has two meanings here, the
secure shell protocol and the npm library. When referring to
the npm library, this repo will always refer to it as the
ssh2-library.
HiveSsh is a wrapper library of the ssh2-library with
additional features and promise-based task execution instead of
a callback function approach.
HiveSsh provides the following key features:
- All-Distributions: SSH2 and SFTP operations for all Linux servers
- Promisified: Promise-based operations for ease of use
- Exec: Command execution utilities for event or promise-based error handling and output parsing, filtering, and mapping
HiveSsh is designed for the following server environment:
- SSH2 server
- Linux distribution
- SFTP support
bun i hivesshor
npm i hivesshPromise based connection to ssh hosts:
import { SshHost } from "hivelib"
// connect
const myHost = await SshHost.connect({
host: "127.0.0.1",
//port: 22, (default 22)
//user: "root", (default root)
password: "123456789",
})
// or
const myHost = await SshHost.connect({
host: "127.0.0.1",
//port: 22, (default 22)
//user: "root", (default root)
privateKey: "...",
//passphrase: "123456789"
})
// or
const myHost = await SshHost.connect({
host: "127.0.0.1",
//port: 22, (default 22)
//user: "root", (default root)
privateKeyPath: "/home/user/.ssh/id_rsa",
//passphrase: "123456789"
})After connecting a SshHost, you can use the promisified
execution (and other asset features) directly on the SshHost
instance:
// check files in user home dir
const homeDirFiles = await myHost.exec("ls -al")
console.log("Home dir files:\n", homeDirFiles.out)You can also execute commands on absolut path:
const etcDirFiles = await myHost.exec("ls -al", { pwd: "/etc" })
console.log("Etc files: ", etcDirFiles.out)Get the hosts public ip address:
// check if curl command exists
const curlExists = await myHost.cmdExists("curl")
if (!curlExists) {
myHost.close()
throw new Error(
"Curl is not installed on: " + myHost.settings.id,
)
}
const myIp = await myHost.exec("curl ifconfig.me")
console.log("Host public ip: " + myIp.out)
//other sources: `api.ipify.org`, `ipinfo.io/ip` or `ipecho.net/plain`Also a git example:
// check if git command exists
const gitExists = await myHost.cmdExists("git")
if (!gitExists) {
myHost.close()
throw new Error(
"Git is not installed on: " + myHost.settings.id,
)
}
// get git status
const gitStatus = await myHost.exec("git status", {
pwd: "/home/tester/myrepo",
})
console.log("Git status:\n", gitStatus.out)You can also use the promisified SFTP features via
SshHost.sftp.
const myBinary: Buffer = await myHost.sftp.readFile(
"/home/tester/my-binary",
)
const exampleConfig: string = await myHost.sftp.readFile(
"/etc/example/config.yml",
"utf8",
)You can find the types in the
npmjs.com build
(at /dist/essentials/SftpPromiseWrapper.d.ts). You can also
check out the ssh2-library
sftp docs
for more background.
This Sessions are reusable command environments that can predefine the current working directory (cwd), user (via sudo), and environment variables for executing mutiple commands. They allow you to run multiple commands consistently without repeatedly specifying paths, users, or settings, making command execution cleaner and more maintainable.
const session = host.session("/etc/example")
session.exec("ls -al") // is executed at /etc/example
session.exec("./myApp") // is using MY_APP_ENV_VARExample with more options:
const session = host.session("/etc/someapp")
// if a other user is needed to execute the process
// login user needs sudo rights without password to switch to that target user
session.asUser = "root"
// set process environment variables for following processes
session.env.TZ = "Europe/Berlin"
session.env.NODE_ENV = "production"
// change directory (without checking if exists) for following processes
// shortcut for session.env.PWD = "/etc/someapp/dist"
session.cd("/etc/someapp/dist")
// execute my app with earlier defined environment
session.exec("bun myApp.js")HiveSsh is built using the following technologies:
- TypeScript
- Bun.js
ssh2-library
Contributions to this project are welcome!
Interested users can follow the guidelines provided in the
CONTRIBUTING.md file to contribute to the
project and help improve its functionality and features.
This project is licensed under the MIT license, which provides users with the flexibility and freedom to use and modify the software according to their needs.
This project is provided "as is".
Users are advised to consult the accompanying licence for
further information on terms of use and limitations of
liability.