# ssh2-connect

> Callback-based api behind ssh2 to open an SSH connection

Latest version **4.2.0** (published 2024-11-26) · MIT license · 0 weekly downloads

## Install

```sh
npm install ssh2-connect
pnpm add ssh2-connect
yarn add ssh2-connect
bun add ssh2-connect
```

## Health

**Score 50/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 4.2.0 |
| Published | 2024-11-26 |
| First published | 2014-04-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=0.10.1 |
| Dependencies | 2 |
| Unpacked size | 42.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 3 |
| Author | David Worms |
| Maintainers | david |
| Keywords | client, exec, remote, secure, sftp, shell, ssh, ssh2 |

## Links

- npm: https://www.npmjs.com/package/ssh2-connect
- Repository: https://github.com/adaltas/node-ssh2-connect
- Issues: https://github.com/adaltas/node-ssh2-connect/issues
- npm.io page: https://npm.io/package/ssh2-connect

## Dependencies (2)

- [ssh2](https://npm.io/package/ssh2.md) ~1.16.0
- [mixme](https://npm.io/package/mixme.md) ^1.1.0

## Alternatives

- [launchdarkly-js-client-sdk](https://npm.io/package/launchdarkly-js-client-sdk.md) — 2.5M weekly downloads
- [@elastic/elasticsearch](https://npm.io/package/@elastic/elasticsearch.md) — 2.1M weekly downloads
- [@c8y/client](https://npm.io/package/@c8y/client.md) — 15.3K weekly downloads
- [@signaldb/maverickjs](https://npm.io/package/@signaldb/maverickjs.md) — 1.7K weekly downloads
- [@bbc/http-transport-cache](https://npm.io/package/@bbc/http-transport-cache.md) — 1.2K weekly downloads

## Recent versions

- 4.2.0 (latest) — 2024-11-26
- 4.1.1 — 2024-10-24
- 4.1.0 — 2024-10-24
- 4.0.3 — 2024-09-28
- 4.0.2 — 2024-09-09
- 4.0.1 — 2024-09-09
- 4.0.0 — 2024-09-09
- 3.5.0 — 2024-09-02
- 3.4.3 — 2024-06-12
- 3.4.2 — 2023-11-19
- 3.4.1 — 2022-06-26
- 3.4.0 — 2022-03-12
- 3.3.1 — 2022-03-12
- 3.3.0 — 2022-03-12
- 3.2.3 — 2022-03-12
- … 20 more at https://npm.io/package/ssh2-connect/versions

## README

# Node.js ssh2-connect

[![Build Status](https://img.shields.io/github/actions/workflow/status/adaltas/node-ssh2-connect/test.yml?branch=master)](https://github.com/adaltas/node-ssh2-connect/actions)
[![NPM](https://img.shields.io/npm/dm/ssh2-connect)](https://www.npmjs.com/package/ssh2-connect)
[![NPM](https://img.shields.io/npm/v/ssh2-connect)](https://www.npmjs.com/package/ssh2-connect)

The Node.js ssh2-connect package extends the [`ssh2`](https://www.npmjs.com/package/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](https://github.com/adaltas/node-ssh2-connect/blob/master/LICENSE.md).

```bash
npm install ssh2-connect
```

## Usage

The `ssh2-connect` module exposes 4 functions.

```js
// 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

```js
// 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](https://www.npmjs.com/package/ssh2#client-methods) 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](https://www.npmjs.com/package/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.

### `close(conn: Client): PromiseLike<boolean>`

Close the the SSH client connection. It resolves to `true` if the connection was opened and closed. Otherwise it resolves to `false`.

- `conn` - The SSH client connection to close.

### `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](https://www.npmjs.com/package/ssh2) code...

```js
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:

```js
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.

```js
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.

```js
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.

```bash
npm install
npm test
```

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

```bash
npm run build
```

The test suite is run online with [GitHub actions](https://github.com/adaltas/node-ssh2-connect/actions) against several Node.js version.

## Release

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

```bash
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](https://www.adaltas.com) based in Paris, France. Adaltas offers support and consulting on distributed systems, big data and open source.

---
_Source: https://npm.io/package/ssh2-connect · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._