{"id":17657545,"url":"https://github.com/NobleMajo/hivessh","last_synced_at":"2025-03-11T03:30:47.042Z","repository":{"id":239363544,"uuid":"788325935","full_name":"NobleMajo/hivessh","owner":"NobleMajo","description":"HiveSSH simplifies SSH2 connections via promise-based task execution on Linux servers with built-in server utilities and powerful command execution functions","archived":false,"fork":false,"pushed_at":"2025-03-08T19:20:31.000Z","size":197,"stargazers_count":37,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-08T22:43:35.922Z","etag":null,"topics":["automation","contributions-welcome","javascript-library","node-ssh","open-source","promise-library","promises","promisified","promisify","server-config","server-configurations","server-controller","serverless","sftp","sftp-client","ssh","ssh-client-library","ssh2","typescirpt","typescript-library"],"latest_commit_sha":null,"homepage":"https://github.com/NobleMajo/HiveSsh","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NobleMajo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-04-18T07:44:11.000Z","updated_at":"2025-03-08T19:20:35.000Z","dependencies_parsed_at":"2025-01-15T10:55:14.192Z","dependency_job_id":"c201354f-b875-4ecf-88a7-96a88d2bc654","html_url":"https://github.com/NobleMajo/hivessh","commit_stats":{"total_commits":74,"total_committers":2,"mean_commits":37.0,"dds":"0.29729729729729726","last_synced_commit":"0fd31077bdd60bbd544b9de45af065bcd9a082d3"},"previous_names":["noblemajo/hivelib"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NobleMajo%2Fhivessh","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NobleMajo%2Fhivessh/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NobleMajo%2Fhivessh/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NobleMajo%2Fhivessh/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NobleMajo","download_url":"https://codeload.github.com/NobleMajo/hivessh/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242967641,"owners_count":20214280,"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":["automation","contributions-welcome","javascript-library","node-ssh","open-source","promise-library","promises","promisified","promisify","server-config","server-configurations","server-controller","serverless","sftp","sftp-client","ssh","ssh-client-library","ssh2","typescirpt","typescript-library"],"created_at":"2024-10-23T14:42:02.780Z","updated_at":"2025-03-11T03:30:47.036Z","avatar_url":"https://github.com/NobleMajo.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HiveSsh\n\n![CI/CD](https://github.com/noblemajo/hivessh/actions/workflows/npm-publish.yml/badge.svg)\n![MIT](https://img.shields.io/badge/license-MIT-blue.svg)\n![typescript](https://img.shields.io/badge/dynamic/json?style=plastic\u0026color=blue\u0026label=Typescript\u0026prefix=v\u0026query=devDependencies.typescript\u0026url=https%3A%2F%2Fraw.githubusercontent.com%2Fnoblemajo%2Fhivessh%2Fmain%2Fpackage.json)\n![npm](https://img.shields.io/npm/v/hivessh.svg?style=plastic\u0026logo=npm\u0026color=red)\n\u003c!-- ![github](https://img.shields.io/badge/dynamic/json?style=plastic\u0026color=darkviolet\u0026label=GitHub\u0026prefix=v\u0026query=version\u0026url=https%3A%2F%2Fraw.githubusercontent.com%2Fnoblemajo%2Fhivessh%2Fmain%2Fpackage.json) --\u003e\n\n![](https://img.shields.io/badge/dynamic/json?color=green\u0026label=watchers\u0026query=watchers\u0026suffix=x\u0026url=https%3A%2F%2Fapi.github.com%2Frepos%2Fnoblemajo%2Fhivessh)\n![](https://img.shields.io/badge/dynamic/json?color=yellow\u0026label=stars\u0026query=stargazers_count\u0026suffix=x\u0026url=https%3A%2F%2Fapi.github.com%2Frepos%2Fnoblemajo%2Fhivessh)\n![](https://img.shields.io/badge/dynamic/json?color=navy\u0026label=forks\u0026query=forks\u0026suffix=x\u0026url=https%3A%2F%2Fapi.github.com%2Frepos%2Fnoblemajo%2Fhivessh)\n\u003c!-- ![](https://img.shields.io/badge/dynamic/json?color=darkred\u0026label=open%20issues\u0026query=open_issues\u0026suffix=x\u0026url=https%3A%2F%2Fapi.github.com%2Frepos%2Fnoblemajo%2Fhivessh)\n![](https://img.shields.io/badge/dynamic/json?color=orange\u0026label=subscribers\u0026query=subscribers_count\u0026suffix=x\u0026url=https%3A%2F%2Fapi.github.com%2Frepos%2Fnoblemajo%2Fhivessh) --\u003e\n\nHiveSsh is an innovative library designed to streamline SSH2 connections and simplify task execution on Linux servers.\n\nIt wraps around the ssh2-library, providing a [promise-based approach](#promisified) to avoid nested callbacks and adding useful features such as [command existence checking](#command-existence-checks) and persistent [exec sessions](#exec-session).\n\n----\n\n- [HiveSsh](#hivessh)\n- [SSH2](#ssh2)\n- [Key features](#key-features)\n- [Requirements](#requirements)\n- [Getting started](#getting-started)\n  - [Promisified](#promisified)\n    - [Execute](#execute)\n    - [Execute at](#execute-at)\n    - [Command existence checks](#command-existence-checks)\n    - [Sftp](#sftp)\n  - [Abstract Package Manager (deprecated)](#abstract-package-manager-deprecated)\n    - [Custom apm](#custom-apm)\n    - [Register package manager](#register-package-manager)\n  - [Exec Session](#exec-session)\n- [Technologies](#technologies)\n- [Contributing](#contributing)\n- [License](#license)\n- [Disclaimer](#disclaimer)\n\n# SSH2\nThe term `ssh2` has two meanings here, the `secure shell protocol` and the `npm library`. \nWhen referring to the npm library, this repo will always refer to it as the `ssh2`-library.\n\nHiveSsh is a wrapper library of the `ssh2`-library with additional features and promise-based task execution instead of a callback function approach.\n\n# Key features\nHiveSsh provides the following key features:\n- __All-Distributions__: SSH2 and SFTP operations for all Linux servers\n- __Promisified__: Promise-based operations for ease of use\n- __AbstractPackageManager__: Built-in abstract package manager with support for apt, dnf, and yum, with additional configurability\n- __Exec__: Command execution utilities for event or promise-based error handling and output parsing, filtering, and mapping\n\n# Requirements\nHiveSsh requires the following server environments:\n- **SSH2 server**\n- **SFTP support**\n- **Linux distribution**\n\n# Getting started\n\n```sh\nnpm i hivessh\n```\n\n```ts\nimport { SshHost } from \"hivelib\"\n\n// connect\nconst myHost = await SshHost.connect({\n    host: \"127.0.0.1\",\n    //port: 22, (default 22)\n    //user: \"root\", (default root)\n\n    password: \"123456789\",\n})\n// or\nconst myHost = await SshHost.connect({\n    host: \"127.0.0.1\",\n    //port: 22, (default 22)\n    //user: \"root\", (default root)\n\n    privateKey: \"...\"\n    //passphrase: \"123456789\"\n})\n// or\nconst myHost = await SshHost.connect({\n    host: \"127.0.0.1\",\n    //port: 22, (default 22)\n    //user: \"root\", (default root)\n\n    privateKeyPath:\"/home/user/.ssh/id_rsa\",\n    //passphrase: \"123456789\"\n})\n```\n\nHere are some using examples:\n\n## Promisified\n### Execute\n\nAfter connecting a `SshHost`, you can use the promisified execution (and other asset features) directly on the `SshHost` instance.\n```ts\n// check files in user home dir\nconst homeDirFiles = await myHost.exec(\"ls -al\")\nconsole.log(\"Home dir files:\\n\", homeDirFiles.out)\n```\n\n### Execute at\n\nYou can also execute commands on absolut path:\n```ts\nconst etcDirFiles = await myHost.exec(\n  \"ls -al\",\n  { pwd: \"/etc\" }\n)\nconsole.log(\"Etc files: \", etcDirFiles.out)\n```\n\n### Command existence checks\n\nGet the hosts public ip address:\n```ts\n// check if curl command exists\nconst curlExists = await myHost.cmdExists(\"curl\")\nif(!curlExists){\n  myHost.close()\n  throw new Error(\"Curl is not installed on: \" + myHost.settings.id)\n}\n\nconst myIp = await myHost.exec(\"curl ifconfig.me\")\nconsole.log(\"Host public ip: \" + myIp.out)\n//other sources: `api.ipify.org`, `ipinfo.io/ip` or `ipecho.net/plain`\n```\n\nAlso a git example:\n```ts\n// check if git command exists\nconst gitExists = await myHost.cmdExists(\"git\")\nif(!gitExists){\n  myHost.close()\n  throw new Error(\"Git is not installed on: \" + myHost.settings.id)\n}\n\n// get git status\nconst gitStatus = await myHost.exec(\n  \"git status\",\n  {\n    pwd: \"/home/tester/myrepo\"\n  }\n)\n\nconsole.log(\"Git status:\\n\", gitStatus.out)\n```\n\n### Sftp\nYou can also use the promisified SFTP features via `SshHost.sftp`.\n```ts\nconst myBinary: Buffer = await myHost.sftp.readFile(\"/home/tester/my-binary\")\n\nconst exampleConfig: string = await myHost.sftp.readFile(\"/etc/example/config.yml\", \"utf8\")\n```\n\nYou can find the types in the [npmjs.com build](https://www.npmjs.com/package/hivessh?activeTab=code) (at /dist/essentials/SftpPromiseWrapper.d.ts).\nYou can also check out the `ssh2`-library [sftp docs](https://github.com/mscdex/ssh2/blob/master/SFTP.md) for more background.\n\n## Abstract Package Manager (deprecated)\nThe AbstractPackageManager (APM) feature will be removed in the future to more focus on the core problems and solutions.\n\nThe abstract package manager (aka `apm`) allows you to use `apt`, `dnf`, `yum` or a `custom implemented package manager` from one interface.\nThe `apm` features are limited and generic, but you can upgrade your system and install, remove and list your packages.\n\n```ts\n// upgrade all packages using the abstract package manager\nconst apm = await myHost.getApm()\nawait apm.updateCache()\nawait apm.upgradeAll()\n\n// install a package using the abstract package manager\nawait apm.install(\"git\")\n```\n\n### Custom apm\n\nTo create a custom `apm`, you need to implement the following typescript interface:\n[https://github.com/NobleMajo/hivessh/blob/main/src/apm/ApmInterface.ts](https://github.com/NobleMajo/hivessh/blob/main/src/apm/ApmInterface.ts)\n\n### Register package manager\n\nAfter implementing the custom package manager, you need to register it globally using a checker function:\n```ts\nimport { apmChecker, AbstractPackageManager } from \"./apm/apm.js\"\n\napmChecker.push(async (host) =\u003e {\n    if (await host.cmdExists(\"myapm\")) {\n        const myApm: AbstractPackageManager = { ... }\n\n        return myApm\n    }\n})\n```\n\nThis function is called when the `getApm()` is called and can return a package manager depending on the host.\n\n## Exec Session\nSessions are available so that the PWD (process working directory) and environment do not have to be specified for each individual command. These sessions store these settings persistently across multiple executions and can even resolve relative paths.\n\n```ts\nconst session = host.session(\"/etc/example\")\n\nsession.exec(\"ls -al\") // is executed at /etc/example\nsession.exec(\"./myApp\") // is using MY_APP_ENV_VAR\n```\n\nExample with more options:\n```ts\nconst session = host.session(\"/etc/someapp\")\n\n//if sudo is needed enable it for following processes\nsession.sudo = true\n\n// set process environment variables for following processes\nsession.env.TZ = \"Europe/Berlin\"\nsession.env.NODE_ENV = \"production\"\n\n// change directory (without checking if exists) for following processes\n// shortcut for session.env.PWD = \"/etc/someapp/dist\"\nsession.cd(\"/etc/someapp/dist\")\n\n// execute my app with earlier defined environment\nsession.exec(\"node myApp.js\")\n```\n\n# Technologies\nHiveSsh is built using the following technologies:\n- **TypeScript**\n- **Node.js**\n- [`ssh2`-library](https://www.npmjs.com/package/ssh2)\n\n# Contributing\nContributions to this project are welcome!  \nInterested users can follow the guidelines provided in the [CONTRIBUTING.md](CONTRIBUTING.md) file to contribute to the project and help improve its functionality and features.\n\n# License\nThis project is licensed under the [MIT](LICENSE) license, which provides users with the flexibility and freedom to use and modify the software according to their needs.\n\n# Disclaimer\nThis project is provided \"as is\".  \nUsers are advised to consult the accompanying licence for further information on terms of use and limitations of liability.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNobleMajo%2Fhivessh","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FNobleMajo%2Fhivessh","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNobleMajo%2Fhivessh/lists"}