npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

ssh2-connect

v4.1.1

Published

Callback-based api behind ssh2 to open an SSH connection

Downloads

4,751

Readme

Node.js ssh2-connect

Build Status NPM NPM

The Node.js ssh2-connect package extends the ssh2 module to provide a simplified callback-back approach to initiate a new SSH connection.

Installation

The project is OSS and licensed under the MIT license.

npm install ssh2-connect

Usage

The ssh2-connect module exposes 4 functions.

// With ESM
import { connect, is, closed, opened } from "ssh2-connect";
// Or with CommonJS
const { connect, is, closed, opened } = require("ssh2-connect");

Use connect to establishes the SSH connection

// Establishes the SSH connection
const client = await connect({
  host: "example.com",
  username: "user",
  privateKeyPath: "~/.ssh/id_ed25519",
});

await connect(options: ConnectConfig): PromiseLike<Client>

The connect function return a promise.

Options are inherited from the ssh2 connect method with a few additions.

  • options - The configuration options for the SSH connection.
  • options.username - The username for authentication. Defaults to the current user if not provided.
  • options.retry - The number of connection retry attempts. Set to 0 or false to disable retries, default is 1.
  • options.wait - The wait time in milliseconds between each attempts, default to 500.
  • options.privateKey - The private key as a string or Buffer for authentication.
  • options.privateKeyPath - The path to the private key file, or true for auto-discovery in ~/.ssh.
  • options.password - The password for authentication.
  • options.[key: string] - Any other valid SSH2 connection options.

Note, the "privateKeyPath" option is provided as a conveniency to read the private key and fill the "privateKey" property.

Additionally, all options may be provided in camalize (the default in ssh2) and snake cases. For example, both "privateKey" and "private_key" would be interprated the same.

is(conn: unknown): boolean

Checks if the provided argument conn is an instance of the Client connection class from the ssh2 package.

  • conn - The object to check, probably an SSH client connection.

closed(conn: Client): boolean

Checks if the provided SSH client connection is closed.

  • conn - The SSH client connection to check.

opened(conn: Client): boolean

Checks if the provided SSH client connection is open and writable.

  • conn - The SSH client connection to check.

Purpose

This package simplifies the creation and the usage of an SSH connection. For example, the original ssh2 code...

import ssh2 from "ssh2";
const connection = new ssh2();
connection.on("error", function (err) {
  // Handle the connection error
  connection.end();
});
connection.on("ready", function () {
  // Work with the connection
  connection.end();
});
connection.connect({
  host: "localhost",
  user: "milou",
  password: "wafwaf",
});

Is simplified to:

import { connect } from "ssh2-connect";
try {
  const ssh = await connect({
    host: "localhost",
    username: "milou",
    private_key_path: "~/.ssh/id_ed25519",
  });
  // Work with the connection, then close it
} catch (err) {
  // Handle the connection error
} finally {
  // Close the connection
  ssh.end();
}

Examples

The example is using both the "ssh2-connect" and "ssh2-fs" modules.

const connect = require("ssh2-connect");
const fs = require("ssh2-fs");
// Open the connection
connect({host: "localhost"}, function(err, ssh){
  // Create a directory
  fs.mkdir(ssh, "/tmp/a_dir", (err, stdout, stderr){
    console.log(stdout);
  });
});

Compare this to the more verbose alternative using the original ssh2 module.

ssh2 = require("ssh2");
fs = require("ssh2-fs");
connection = new ssh2();
connection.on("error", function(err){
  connection.end()
});
connection.on("ready", function(){
  fs.mkdir(connection, "/tmp/a_dir", (err, stdout, stderr){
    console.log(stdout);
  });
});
connection.connect({host: "localhost"});

Development

Tests are executed with mocha. To install it, run npm install, it will install mocha and its dependencies in your project "node_modules" directory.

npm install
npm test

Source code is written in Typescription. The build command generates the JavaScript files.

npm run build

The test suite is run online with GitHub actions against several Node.js version.

Release

Versions are incremented using semantic versioning. To create a new version and publish it to NPM, run:

npm run release
# Or (`git push` is only supported for the release script)
npm run release:<major|minor|patch>
git push --follow-tags origin master

The NPM publication is handled with the GitHub action.

Contributors

The project is sponsored by Adaltas based in Paris, France. Adaltas offers support and consulting on distributed systems, big data and open source.