node-ssh

node-ssh requires @types/ssh2 for TypeScript support. Install it as a development dependency.

# Using npm
npm install --save-dev @types/ssh2

# Using yarn
yarn add --dev @types/ssh2

If you encounter issues, ensure your tsconfig.json includes the following settings:

{
  "compilerOptions": {
    "moduleResolution": "node",
    "allowSyntheticDefaultImports": true
  }
}

You can install node-ssh using npm or Yarn.

$ npm install node-ssh # If you're using npm
$ yarn add node-ssh # If you're using Yarn

If your server requires keyboard-interactive authentication, set tryKeyboard: true in your connection config. You can also provide a custom onKeyboardInteractive handler to respond to specific prompts.

ssh.connect({
  host: 'localhost',
  username: 'steel',
  port: 22,
  password: 'test',
  tryKeyboard: true,
  onKeyboardInteractive(name, instructions, instructionsLang, prompts, finish) {
    if (prompts.length > 0 && prompts[0].prompt.toLowerCase().includes('password')) {
      finish(['test'])
    }
  }
})

To establish a connection, instantiate NodeSSH and call .connect(config). You can authenticate using a privateKeyPath or an inline privateKey (as a Buffer).

const {NodeSSH} = require('node-ssh')
const ssh = new NodeSSH()

// Using a private key file path
ssh.connect({
  host: 'localhost',
  username: 'steel',
  privateKeyPath: '/home/steel/.ssh/id_rsa'
})

// OR using an inline private key
ssh.connect({
  host: 'localhost',
  username: 'steel',
  privateKey: Buffer.from('...')
})

node-ssh supports several file transfer methods:

• putFile(localFile, remoteFile, ...): Uploads a single file.
• putFiles(files, options): Uploads an array of files defined as { local: string, remote: string }[].
• getFile(localFile, remoteFile, ...): Downloads a file from the remote server.
• putDirectory(localDirectory, remoteDirectory, options): Uploads an entire directory. Supports recursive transfers and a validate function to filter files.

Example: Uploading a directory with validation

ssh.putDirectory('/home/steel/Lab', '/home/steel/Lab', {
  recursive: true,
  concurrency: 10,
  validate: function(itemPath) {
    const baseName = path.basename(itemPath)
    return baseName.substr(0, 1) !== '.' && baseName !== 'node_modules'
  }
})

ssh.putFile('/home/steel/Lab/localPath/fileName', '/home/steel/Lab/remotePath/fileName')

To ensure resources are properly cleaned up, use the withShell and withSFTP helper methods. These methods automatically destroy the channel or end the SFTP session once the provided callback completes.

• withShell(callback, options): Provides a ClientChannel to the callback.
• withSFTP(callback): Provides an SFTPWrapper to the callback.

// Using withSFTP for safe resource management
await ssh.withSFTP(async (sftp) => {
  const stats = await sftp.stat('/remote/path');
  console.log(stats.size);
});

The execCommand(givenCommand: string, options?: SSHExecCommandOptions) method executes a single command and returns a promise that resolves to an SSHExecCommandResponse object containing stdout, stderr, code, and signal.

Options:

• cwd: The working directory for the command.
• stdin: A string or readable stream to pass to the command's standard input.
• onStdout / onStderr: Callbacks for receiving data chunks as they arrive.
• noTrim: If true, prevents the automatic trimming of stdout and stderr results.

const result = await ssh.execCommand('ls -la', { cwd: '/var/log' });
console.log(result.stdout);

Node-SSH supports both TCP and Unix socket forwarding:

TCP Forwarding

• forwardIn(remoteAddr, remotePort, onConnection?): Forwards a port from the remote server to your local machine. Returns a dispose function to stop the forwarding.
• forwardOut(srcIP, srcPort, dstIP, dstPort): Forwards a port from your local machine to a destination via the SSH server. Returns a Channel.

Unix Socket Forwarding

• forwardInStreamLocal(socketPath, onConnection?): Forwards a remote Unix socket to a local socket path.
• forwardOutStreamLocal(socketPath): Forwards a local Unix socket to the remote server.

// TCP Forwarding In
const { port, dispose } = await ssh.forwardIn('127.0.0.1', 8080);
console.log(`Forwarding on local port: ${port}`);

// Stop forwarding later
await dispose();

The exec(command: string, parameters: string[], options?: SSHExecOptions) method is a high-level wrapper for execCommand. It automatically escapes parameters to prevent shell injection.

Return Values based on options.stream:

• If options.stream is undefined or 'stdout': Returns a Promise<string> containing the trimmed stdout. It throws an error if stderr is not empty.
• If options.stream is 'stderr': Returns a Promise<string> containing the trimmed stderr.
• If options.stream is 'both': Returns a Promise<SSHExecCommandResponse> containing the full response object.

// Returns stdout as a string
const output = await ssh.exec('ls', ['-la', '/tmp']);

// Returns full response object
const response = await ssh.exec('git', ['status'], { stream: 'both' });

Create directories on the remote server using mkdir(path: string, method: SSHMkdirMethod = 'sftp', givenSftp?: SFTPWrapper).

Methods:

• 'sftp' (default): Uses the SFTP protocol. It will attempt to create parent directories recursively if they do not exist.
• 'exec': Uses a shell command (mkdir -p) to create the directory.

If you are performing multiple directory operations, passing an existing SFTPWrapper via givenSftp is more efficient as it avoids re-establishing an SFTP session.

// Using SFTP (default)
await ssh.mkdir('/home/user/new_folder/sub_folder');

// Using exec
await ssh.mkdir('/home/user/new_folder', 'exec');