Node-SSH - SSH2 with Promises

Node-SSH is an extremely lightweight Promise wrapper for ssh2.

Installation

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

Example

1const fs = require('fs')
2const path = require('path')
3const {NodeSSH} = require('node-ssh')
4
5const ssh = new NodeSSH()
6
7ssh.connect({
8  host: 'localhost',
9  username: 'steel',
10  privateKeyPath: '/home/steel/.ssh/id_rsa'
11})
12
13// or with inline privateKey
14
15ssh.connect({
16  host: 'localhost',
17  username: 'steel',
18  privateKey: Buffer.from('...')
19})
20.then(function() {
21  // Local, Remote
22  ssh.putFile('/home/steel/Lab/localPath/fileName', '/home/steel/Lab/remotePath/fileName').then(function() {
23    console.log("The File thing is done")
24  }, function(error) {
25    console.log("Something's wrong")
26    console.log(error)
27  })
28  // Array<Shape('local' => string, 'remote' => string)>
29  ssh.putFiles([{ local: '/home/steel/Lab/localPath/fileName', remote: '/home/steel/Lab/remotePath/fileName' }]).then(function() {
30    console.log("The File thing is done")
31  }, function(error) {
32    console.log("Something's wrong")
33    console.log(error)
34  })
35  // Local, Remote
36  ssh.getFile('/home/steel/Lab/localPath', '/home/steel/Lab/remotePath').then(function(Contents) {
37    console.log("The File's contents were successfully downloaded")
38  }, function(error) {
39    console.log("Something's wrong")
40    console.log(error)
41  })
42  // Putting entire directories
43  const failed = []
44  const successful = []
45  ssh.putDirectory('/home/steel/Lab', '/home/steel/Lab', {
46    recursive: true,
47    concurrency: 10,
48    // ^ WARNING: Not all servers support high concurrency
49    // try a bunch of values and see what works on your server
50    validate: function(itemPath) {
51      const baseName = path.basename(itemPath)
52      return baseName.substr(0, 1) !== '.' && // do not allow dot files
53             baseName !== 'node_modules' // do not allow node_modules
54    },
55    tick: function(localPath, remotePath, error) {
56      if (error) {
57        failed.push(localPath)
58      } else {
59        successful.push(localPath)
60      }
61    }
62  }).then(function(status) {
63    console.log('the directory transfer was', status ? 'successful' : 'unsuccessful')
64    console.log('failed transfers', failed.join(', '))
65    console.log('successful transfers', successful.join(', '))
66  })
67  // Command
68  ssh.execCommand('hh_client --json', { cwd:'/var/www' }).then(function(result) {
69    console.log('STDOUT: ' + result.stdout)
70    console.log('STDERR: ' + result.stderr)
71  })
72  // Command with escaped params
73  ssh.exec('hh_client', ['--json'], { cwd: '/var/www', stream: 'stdout', options: { pty: true } }).then(function(result) {
74    console.log('STDOUT: ' + result)
75  })
76  // With streaming stdout/stderr callbacks
77  ssh.exec('hh_client', ['--json'], {
78    cwd: '/var/www',
79    onStdout(chunk) {
80      console.log('stdoutChunk', chunk.toString('utf8'))
81    },
82    onStderr(chunk) {
83      console.log('stderrChunk', chunk.toString('utf8'))
84    },
85  })
86})

API

1// API reference in Typescript typing format:
2import stream from 'stream'
3import { Client, ConnectConfig, ClientChannel, SFTPWrapper, ExecOptions, PseudoTtyOptions | ShellOptions } from 'ssh2';
4import { Prompt, TransferOptions } from 'ssh2-streams';
5// ^ You do NOT need to import these package, these are here for reference of where the
6// types are coming from.
7
8declare type Config = ConnectConfig & {
9    host?: string;
10    port?: number;
11    username?: string;
12    password?: string;
13    privateKeyPath?: string;
14    privateKey?: string;
15    passphrase?: string;
16    tryKeyboard?: boolean;
17    onKeyboardInteractive?: (
18      name: string,
19      instructions: string,
20      lang: string,
21      prompts: Prompt[],
22      finish: (responses: string[]) => void
23    ) => void;
24};
25
26interface SSHExecCommandOptions {
27    cwd?: string;
28    stdin?: string | stream.Readable;
29    execOptions?: ExecOptions;
30    encoding?: BufferEncoding;
31    onChannel?: (clientChannel: ClientChannel) => void;
32    onStdout?: (chunk: Buffer) => void;
33    onStderr?: (chunk: Buffer) => void;
34}
35
36interface SSHExecCommandResponse {
37    stdout: string;
38    stderr: string;
39    code: number | null;
40    signal: string | null;
41}
42
43interface SSHExecOptions extends SSHExecCommandOptions {
44    stream?: 'stdout' | 'stderr' | 'both';
45}
46
47interface SSHPutFilesOptions {
48    sftp?: SFTPWrapper | null;
49    concurrency?: number;
50    transferOptions?: TransferOptions;
51}
52
53interface SSHGetPutDirectoryOptions extends SSHPutFilesOptions {
54    tick?: (localFile: string, remoteFile: string, error: Error | null) => void;
55    validate?: (path: string) => boolean;
56    recursive?: boolean;
57}
58
59type SSHForwardInListener = (
60  details: TcpConnectionDetails,
61  accept: AcceptConnection<ClientChannel>,
62  reject: RejectConnection,
63) => void
64interface SSHForwardInDetails {
65  dispose(): Promise<void>
66  port: number
67}
68
69type SSHForwardInStreamLocalListener = (
70  info: UNIXConnectionDetails,
71  accept: AcceptConnection,
72  reject: RejectConnection,
73) => void
74interface SSHForwardInStreamLocalDetails {
75  dispose(): Promise<void>
76}
77
78class NodeSSH {
79    connection: Client | null;
80
81    connect(config: Config): Promise<this>;
82
83    isConnected(): boolean;
84
85    requestShell(
86      options?: PseudoTtyOptions | ShellOptions | false
87    ): Promise<ClientChannel>;
88
89    withShell(
90      callback: (channel: ClientChannel) => Promise<void>,
91      options?: PseudoTtyOptions | ShellOptions | false
92    ): Promise<void>;
93
94    requestSFTP(): Promise<SFTPWrapper>;
95
96    withSFTP(
97      callback: (sftp: SFTPWrapper) => Promise<void>
98    ): Promise<void>;
99
100    execCommand(
101      command: string,
102      options?: SSHExecCommandOptions
103    ): Promise<SSHExecCommandResponse>;
104
105    exec(
106      command: string,
107      parameters: string[],
108      options?: SSHExecOptions & {
109          stream?: 'stdout' | 'stderr';
110      }
111    ): Promise<string>;
112
113    exec(
114      command: string,
115      parameters: string[],
116      options?: SSHExecOptions & {
117          stream: 'both';
118      }
119    ): Promise<SSHExecCommandResponse>;
120
121    mkdir(
122      path: string,
123      method?: 'sftp' | 'exec',
124      sftp?: SFTPWrapper | null
125    ): Promise<void>;
126
127    getFile(
128      localFile: string,
129      remoteFile: string,
130      sftp?: SFTPWrapper | null,
131      transferOptions?: TransferOptions | null
132    ): Promise<void>;
133
134    putFile(
135      localFile: string,
136      remoteFile: string,
137      sftp?: SFTPWrapper | null,
138      transferOptions?: TransferOptions | null
139    ): Promise<void>;
140
141    putFiles(files: Array<{
142        local: string;
143        remote: string;
144    }>, options?: SSHPutFilesOptions): Promise<void>;
145
146    putDirectory(
147      localDirectory: string,
148      remoteDirectory: string,
149      options?: SSHGetPutDirectoryOptions
150    ): Promise<boolean>;
151
152    getDirectory(
153      localDirectory: string,
154      remoteDirectory: string,
155      options?: SSHGetPutDirectoryOptions
156    ): Promise<boolean>;
157
158
159    forwardIn(
160      remoteAddr: string,
161      remotePort: number,
162      onConnection?: SSHForwardInListener
163    ): Promise<SSHForwardInDetails>;
164
165    forwardOut(
166      srcIP: string,
167      srcPort: number,
168      dstIP: string,
169      dstPort: number
170    ): Promise<Channel>;
171
172    forwardInStreamLocal(
173      socketPath: string,
174      onConnection?: SSHForwardInStreamLocalListener,
175    ): Promise<SSHForwardInStreamLocalDetails>;
176
177    forwardOutStreamLocal(
178      socketPath: string
179    ): Promise<Channel>;
180
181    dispose(): void;
182}
183
184module.exports = NodeSSH;

Typescript support

node-ssh requires extra dependencies while working under Typescript. Please install them as shown below

yarn add --dev @types/ssh2
# OR
npm install --save-dev @types/ssh2

If you're still running into issues, try adding these to your tsconfig.json

1{
2  "compilerOptions": {
3    "moduleResolution": "node",
4    "allowSyntheticDefaultImports": true
5  }
6}

Keyboard-interactive user authentication

In some cases you have to enable keyboard-interactive user authentication. Otherwise you will get an All configured authentication methods failed error.

Example:

1const password = 'test'
2
3ssh.connect({
4  host: 'localhost',
5  username: 'steel',
6  port: 22,
7  password,
8  tryKeyboard: true,
9})
10
11// Or if you want to add some custom keyboard-interactive logic:
12
13ssh.connect({
14  host: 'localhost',
15  username: 'steel',
16  port: 22,
17  tryKeyboard: true,
18  onKeyboardInteractive(name, instructions, instructionsLang, prompts, finish) {
19    if (prompts.length > 0 && prompts[0].prompt.toLowerCase().includes('password')) {
20      finish([password])
21    }
22  }
23})

For further information see: https://github.com/mscdex/ssh2/issues/604

License

This project is licensed under the terms of MIT license. See the LICENSE file for more info.