Note: I really don't work on this project anymore. It's still fully functional, I'm just not interested in working on it anymore. If you post an issue, I might respond and I might not. If you submit a pull request, I'll most likely accept it. Hopefully it continues to help people around the world. :earth_americas:

simple-ssh

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

Requirements

* [node.js][2] -- v0.8.7 or newer

Install

npm install simple-ssh

Examples

* Echoing out a users PATH:

``javascript
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();
`

* Connecting with the active SSH Agent with Agent Forwarding

`javascript
var ssh = new ssh({
host: 'localhost',
user: 'username',
agent: process.env.SSH_AUTH_SOCK,
agentForward: true
})
`

* Capturing error output:

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

* Capturing error codes:

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

* Sending data to stdin:

`javascript
ssh.exec('cat > /path/to/remote/file', {
in: fs.readFileSync('/path/to/local/file')
}).start();
`

* Chaining commands together:

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

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

* Get the number of commands:

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

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

* Running a command using sudo

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

* Resetting a connection and the commands

`javascript
// 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

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

* Event handlers can be chained as well

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

----------

API

$3

* Constructor( [ _config_ ] )
* config { _Object_ }:
* config.host { _String_ }: Hostname
* config.port { _Number_ }: Port number (default: 22)
* config.user { _String_ }: Username
* config.pass { _String_ }: Password
* config.timeout { _Number_ }: Connection timeout in milliseconds (default: 10000)
* config.key { _String_ }: SSH key
* config.passphrase { _String_ }: Passphrase
* config.baseDir { _String_ }: Base directory. If this is set, each command will be preceeded by cd ${this.baseDir}
* config.agent { _String_ }: Connects with the given SSH agent. If this is set, no need to specify a private key or password.
* config.agentForward { _Boolean_ }: Set to true to connect with agent forwarding.
* 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.in { _String_ }: Input to be sent to stdin
* 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][3])
* 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).

$3

* host { _String_ }: Host to connect to
* port { _Number_ }: Port to connect through (default: 22)
* user { _String_ }: User name
* pass { _String_ }: Password
* timeout { _Number_ }: Connection timeout in milliseconds (default: 10000)
* key { _String_ }: SSH key
* baseDir { _String_ }: If set, will change directory to baseDir before each command

$3

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:

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

* Running a new queue of commands:

`javascript
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();
``

[1]: https://github.com/mscdex/ssh2
[2]: http://nodejs.org
[3]: https://github.com/alexjab