simple-ssh

simple-ssh

A wrapper for the ssh2 client module by Brian White which makes it easier to run a sequence of commands over SSH.

Requirements

• node.js -- v0.8.7 or newer

Install

npm install simple-ssh

Examples

• Echoing out a users PATH:

var SSH = require('simple-ssh');

var ssh = new SSH({
    host: 'localhost',
    user: 'username',
    pass: 'password'
});

ssh.exec('echo $PATH', {
    out: function(stdout) {
        console.log(stdout);
    }
}).start();

/*** Using the `args` options instead ***/
ssh.exec('echo', {
    args: ['$PATH'],
    out: function(stdout) {
        console.log(stdout);
    }
}).start();

• Capturing error output:

ssh.exec('this-does-not-exist', {
    err: function(stderr) {
        console.log(stderr); // this-does-not-exist: command not found
    }
}).start();

• Capturing error codes:

ssh.exec('exit 69', {
    exit: function(code) {
        console.log(code); // 69
    }
}).start();

• Chaining commands together:

ssh
    .exec('echo "Node.js"', {
        out: console.log
    })
    .exec('echo "is"', {
        out: console.log
    })
    .exec('echo "awesome!"', {
        out: console.log
    })
    .start();

// Output:
// Node.js
// is
// awesome!

• Get the number of commands:

ssh
    .exec('exit 1')
    .exec('exit 2')
    .exec('exit 3');

console.log(ssh.count()); // 3

• Running a command using sudo

ssh.exec('sudo echo "Pseudo-sudo"', {
    pty: true,
    out: console.log
}).start();

• Resetting a connection and the commands

// Echos out any messages the user sent in if 10 or more have been queued
var msgInterval = setInterval(function() {
    if (ssh.count() > 10) {
        ssh.start();
    }
}, 1000);

socket.on('message', function(msg) {
    // If a 'reset' message is received, clear previous messages
    if (msg === 'reset') {
        ssh.reset(function(err) {
            if (err) {
                throw err;
            }

            ssh.exec('echo "reset"');
        });
    } else {
        ssh.exec('echo "' + msg + '"');
    }
});

• Listening for additional events

ssh.on('error', function(err) {
    console.log('Oops, something went wrong.');
    console.log(err);
    ssh.end();
});

• Event handlers can be chained as well

ssh
    .on('error', onSSHError)
    .on('ready', onSSHReady);

---

API

Functions

• Constructor( [ config ] )
  • config { Object }:
    • config.host { String }: Hostname
    • config.port { Number }: Port number (default: 22)
    • config.user { String }: Username
    • config.pass { String }: Password
• exec( command, [ options ] ): Adds a command to the stack
  • command { String }: Command to be executed
  • options { Object }:
    • options.args { String[] }: Additional command line arguments (default: null)
    • options.out { Function( stdout ) }: stdout handler
      • stdout { String }: Output streamed through stdout
    • options.err { Function( stderr ) }: stderr handler
      • stderr { String }: Output streamed through stderr
    • options.exit { Function( code, stdout, stderr ) }: Exit handler
      • code { Number }: Exit code
      • stdout { String }: All of the standard output concatenated together
      • stderr { String }: All of the error output concatenated together
    • options.pty { Boolean }: Allocates a pseudo-tty, useful for command which require sudo (default: false)
• on( event, callback ): Add a listener for the specified event (Courtesy of @alexjab)
  • event { String }: Event to listen to
  • callback { Function }: Executed on the event
• start( [ options ] ): Starts executing the commands
  • options { Object }:
    • options.success { Function() }: Called on successful connection
    • options.fail { Function( err ) }: Called if the connection failed
      • err { Error }: Error information
• reset( [ callback ] ): Clears the command queue and resets the current connection
  • callback { Function( err ) }: Called when the connection has been successfully reset
    • err { Error }: Error information
• end(): Ends the SSH session (this is automatically called at the end of a command queue).

Flow Control

Sometimes you may find yourself needing to change which commands are executed. The flow can be changed by returning false from an exit handler.

Note: This only works if false is explicitly returned. "Falsy" values are not sufficient (since undefined is implicitly returned and it's "falsy").

• Ending prematurely:

ssh
    .exec('pwd', {
        exit: function() {
            return false;
        }
    })
    .exec('echo "Not executed"')
    .start();

• Running a new queue of commands:

ssh
    .exec('exit', {
        args: [ Math.round(Math.random()) ],
        exit: function(code) {
            if (code === 1) {
                // Setup the new command queue
                ssh.exec('echo "new queue"');
                return false;
            }
        }
    })
    .exec('exit 0', {
        exit: function() {
            console.log('Previous command did not return false');
        }
    })
    .start();