Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/MCluck90/simple-ssh
A simple wrapper for Brian White's ssh2 module to make it easier to perform sequential commands.
https://github.com/MCluck90/simple-ssh
javascript ssh ssh2
Last synced: 4 months ago
JSON representation
A simple wrapper for Brian White's ssh2 module to make it easier to perform sequential commands.
- Host: GitHub
- URL: https://github.com/MCluck90/simple-ssh
- Owner: MCluck90
- License: mit
- Created: 2013-07-14T19:15:46.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2022-12-11T14:29:49.000Z (about 2 years ago)
- Last Synced: 2024-04-13T21:56:55.236Z (8 months ago)
- Topics: javascript, ssh, ssh2
- Language: JavaScript
- Size: 93.8 KB
- Stars: 194
- Watchers: 8
- Forks: 37
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
**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
### Functions
* **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).
### Properties
* **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
### 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:
```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