simple-ssh

A wrapper for ssh2 to make it easier to perform commands over SSH

npm install simple-ssh
1 downloads in the last day
19 downloads in the last week
59 downloads in the last month

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

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 @alexandrejablon)
    • 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();
npm loves you