SSH2 Client and Server for Node.js

Common errors

• Error: All configured authentication methods failed

  cause The SSH server rejected all attempted authentication methods (e.g., password, private key). This usually means incorrect credentials, an invalid private key, or the server not supporting the client's offered authentication methods.
  fix Verify the `username`, `password`, or `privateKey` used in the `connect` options. Ensure the `privateKey` path is correct and the key file is readable by the Node.js process. Check server logs for more details on authentication failures.

• Error: connect ECONNREFUSED

  cause The client could not establish a TCP connection to the specified host and port. This typically indicates the SSH server is not running, is not accessible from the client's network, or a firewall is blocking the connection.
  fix Confirm the `host` and `port` are correct. Check if the SSH server process is running on the target machine. Verify network connectivity and firewall rules between the client and server.

• Error: privateKey is required

  cause The `privateKey` option was provided with an empty or undefined value, or the file path was incorrect leading to an empty buffer.
  fix Ensure `privateKey` is correctly populated, either directly with a key string or by reading a valid key file using `readFileSync`. Double-check the path to the private key file.

Warnings

• breaking Version 1.0.0 introduced significant breaking changes. Key classes like `Client` and `Server` became named exports instead of default exports or properties of the main module object. API method signatures, particularly for `Client.exec` and `Client.shell`, changed to pass the stream directly to the callback rather than returning it. `SFTPStream` and `Channel` are no longer directly exported.
  Fix: Review the v1.0.0 breaking changes detailed in the GitHub issue #935 (linked in the README) and update import statements and method calls accordingly. Use named imports for `Client` and `Server`.
• breaking The `hostVerifier()` client option will now be called every time a handshake occurs, including during rekeying. Ensure your host verification logic handles this repeated invocation.
  Fix: Adjust `hostVerifier()` implementations to be idempotent and handle multiple calls per connection, including during rekey events.
• gotcha Node.js v10.16.0 or newer is required. For Ed25519 key support, Node.js v12.0.0 or newer is necessary.
  Fix: Ensure your Node.js environment meets the minimum version requirements. Upgrade Node.js to at least v12.0.0 for full key type compatibility.
• gotcha The `cpu-features` package is an optional dependency used to optimize cipher list generation. If it fails to install or build, `ssh2` will still function but might use a less optimal default cipher list.
  Fix: While not strictly required, resolving `cpu-features` installation issues (e.g., build toolchain problems) can improve performance. Check `cpu-features` documentation for its specific system requirements.

Install

• npm install ssh2 npm
• yarn add ssh2 yarn
• pnpm add ssh2 pnpm

Imports

• Client
  wrong:

  const Client = require('ssh2');

  correct:

  import { Client } from 'ssh2';

  Since v1.0.0, Client is a named export. Older versions might have had it as a default export or directly on the `require('ssh2')` object. Using named import/require is the modern and correct approach.
• Server
  wrong:

  const Server = require('ssh2');

  correct:

  import { Server } from 'ssh2';

  Similar to Client, Server is a named export since v1.0.0. Ensure you destructure it from the module.
• utils
  wrong:

  import { utils } from 'ssh2';

  correct:

  import * as utils from 'ssh2/lib/utils';

  Utility functions like `parseKey` are typically found in a separate `lib/utils` path and imported as a module. Direct named import from `ssh2` might not expose all utilities or could change.

Quickstart

This example demonstrates how to establish an SSH client connection to a server and execute a remote command ('uptime'), logging its standard output and error.

const { readFileSync } = require('fs');
const { Client } = require('ssh2');

const conn = new Client();
conn.on('ready', () => {
  console.log('Client :: ready');
  conn.exec('uptime', (err, stream) => {
    if (err) throw err;
    stream.on('close', (code, signal) => {
      console.log(`Stream :: close :: code: ${code}, signal: ${signal}`);
      conn.end();
    }).on('data', (data) => {
      console.log('STDOUT: ' + data);
    }).stderr.on('data', (data) => {
      console.error('STDERR: ' + data);
    });
  });
}).on('error', (err) => {
  console.error('Client Error:', err.message);
}).connect({
  host: process.env.SSH_HOST ?? '127.0.0.1',
  port: parseInt(process.env.SSH_PORT ?? '22', 10),
  username: process.env.SSH_USERNAME ?? 'user',
  privateKey: readFileSync(process.env.SSH_PRIVATE_KEY_PATH ?? './id_rsa')
});