ssh2-connect

Callback-based api behind ssh2 to open an SSH connection

Node.js ssh2-connect

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

Function signature is connect(options, callback).

The main purpose of this module is to simplify the creation of an SSH connection. For example, the original ssh2 code...

ssh2 = require 'ssh2'
connection = new ssh2()
connection.on 'error'(err) ->
  connection.end()
  # not ready at all 
connection.on 'ready'->
  # ready to go 
connection.connect options

...is simplified to:

connect = require 'ssh2-exec/lib/connect'
connect options(err, ssh) ->
  # this is faster to write 

Options are inherited from the ssh2 Connection.prototype.connect function with a few additions:

  • username
    The username used to initiate the connection, default to the current environment user.
  • privateKeyPath
    Path to the file containing the private key.
  • retry Attempt to reconnect multiple times, default to "1".
  • wait Time to wait in milliseconds between each retry, default to "500".

Note, the "privateKeyPath" option is provided as a conveniency to prepare the "privateKey" property.

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

This is OSS and licensed under the new BSD license.

npm install ssh2-connect

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

connect = require('ssh2-connect');
fs = require('ssh2-fs');
connect({host: 'localhost'}, function(errssh){
  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'});

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

To run the tests:

npm test

The tests run against the CoffeeScript source files.

To generate the JavaScript files:

make build

The test suite is run online with Travis against Node.js version 0.9, 0.10 and 0.11.