SSH2Utils 

A library to ease use of excellent modules ssh2.

Provide a set of methods to exec/run/getFile/putFile/getDir/putDir.

---------------------------------------

Install

``npm i ssh2-utils --save`

---------------------------------------

Documentation

Automatic source code documentation generation

is supported by jsdoc at https://maboiteaspam.github.io/ssh2-utils/docs/

Automatic tests documentation generation

is support by mocha https://github.com/maboiteaspam/ssh2-utils/tree/gh-pages/mocha-tests.md

$3

* SSH2Utils
* open
* exec
* run
* runMultiple
* mktemp
* readFile
* readFileSudo
* getFile
* putDir
* putDirSudo
* readDir
* putFile
* putFileSudo
* mkdir
* mkdirSudo
* rmdir
* rmdirSudo
* writeFile
* writeFileSudo
* getDir
* fileExists
* fileExistsSudo
* ensureFileContains
* ensureFileContainsSudo
* ensureEmptyDir
* ensureEmptyDirSudo
* ensureOwnership
* streamReadFile
* streamReadFileSudo

---------------------------------------

$3

$3

Execute a command on remote server and return its output.

__Arguments__

* server - An object of ssh server credentials.
* cmd - A command line to execute on remote.
* callback(err,stdout,stderr,server,conn) - A callback called on command line completion.
* err isa Boolean.
* stdout stderr are String.
* server An ssh server credentials object.
* conn An ssh Client object.

__Examples__

`js
var SSH2Utils = require('ssh2-utils');
var ssh = new SSH2Utils();

var server = {host: "localhost", username:"user", password:"pwd" };

ssh.exec(server, 'ls', function(err,stdout,stderr){
if(err) console.log(err);
console.log(stdout);
console.log(stderr);
});
`

$3

Execute a command on remote server and return its streams.

__Arguments__

* server - An object of ssh server credentials.
* cmd - A command line to execute on remote.
* callback(err,stdout,stderr,server,conn) - A callback called on command line sent.
* err isa Boolean.
* stdout stderr are Streams.
* server An ssh server credentials object.
* conn An ssh Client object.

__Examples__

`js
var SSH2Utils = require('ssh2-utils');
var ssh = new SSH2Utils();

var server = {host: "localhost", username:"user", password:"pwd" };

ssh.run(server, ['ls','time'], function(err,stdout,stderr,server,conn){
if(err) console.log(err);
stdout.on('data', function(){
console.log(''+data);
});
stderr.on('data', function(){
console.log(''+data);
});
stdout.on('close',function(){
conn.end();
});
});
`

$3

$3

Download a file from remote to local.

__Arguments__

* server - An object of ssh server credentials.
* remoteFile - A remote file path to read.
* localPath - A local file path to write.
* callback(err) - A callback called on command line completion.
* err is an Error.
* server An ssh server credentials object.
* conn An ssh Client object.

__Examples__

`js
var SSH2Utils = require('ssh2-utils');
var ssh = new SSH2Utils();

var server = {host: "localhost", username:"user", password:"pwd" };

ssh.getFile(server,'/tmp/from_some_remote','/tmp/to_some_local', function(err){
if(err) console.log(err);
});
`

$3

Put a file from local to remote

__Arguments__

* server - An object of ssh server credentials.
* localFile - A local file path to write.
* remoteFile - A remote file path to read.
* callback(err) - A callback called on command line completion.
* err is an Error.
* server An ssh server credentials object.
* conn An ssh Client object.

__Examples__

`js
var SSH2Utils = require('ssh2-utils');
var ssh = new SSH2Utils();

var server = {host: "localhost", username:"user", password:"pwd" };

ssh.putFile(server,'/tmp/to_some_local','/tmp/from_some_remote', function(err){
if(err) console.log(err);
});
`

$3

Put a local directory contents to a remote path.

__Arguments__

* server - An object of ssh server credentials.
* localPath - A local file path to write.
* remoteFile - A remote file path to read.
* callback(err) - A callback called on command line completion.
* err is an Error.
* server An ssh server credentials object.
* conn An ssh Client object.

__Examples__

`js
var SSH2Utils = require('ssh2-utils');
var ssh = new SSH2Utils();

var server = {host: "localhost", username:"user", password:"pwd" };

ssh.putDir(server,'/tmp/from_some_local','/tmp/to_some_remote', function(err){
if(err) console.log(err);
});
`

$3

Create a directory at remote path.

__Arguments__

* server - An object of ssh server credentials.
* remotePath - A remote path to create.
* callback(err) - A callback called on command line completion.
* err is an Error.
* server An ssh server credentials object.
* conn An ssh Client object.

__Examples__

`js
var SSH2Utils = require('ssh2-utils');
var ssh = new SSH2Utils();

var server = {host: "localhost", username:"user", password:"pwd" };

ssh.mkdir(server,'/tmp/to_some_remote', function(err){
if(err) console.log(err);
});
`

$3

Deletes a directory at remote path.

Effectively performs rm -fr remotePath.

__Arguments__

* server - An object of ssh server credentials.
* remotePath - A remote path to delete.
* callback(err) - A callback called on command line completion.
* err is an Error.
* server An ssh server credentials object.
* conn An ssh Client object.

__Examples__

`js
var SSH2Utils = require('ssh2-utils');
var ssh = new SSH2Utils();

var server = {host: "localhost", username:"user", password:"pwd" };

ssh.rmdir(server,'/tmp/to_some_remote', function(err){
if(err) console.log(err);
});
`

$3

Tests a path on remote.

__Arguments__

* server - An object of ssh server credentials.
* remotePath - A remote path to tests.
* callback(err) - A callback called on command line completion.
* err is an Error if file does not exists.
* server An ssh server credentials object.
* conn An ssh Client object.

__Examples__

`js
var SSH2Utils = require('ssh2-utils');
var ssh = new SSH2Utils();

var server = {host: "localhost", username:"user", password:"pwd" };

ssh.fileExists(server,'/tmp/to_some_remote', function(err){
if(err) console.log(err);
});
`


---------------------------------------

Suggestions

On linux you may want to edit /etc/ssh/ssh_config and append
`
Host 127.0.0.1
CheckHostIP no
StrictHostKeyChecking no
UserKnownHostsFile=/dev/null
`

This will help to have multiple vagrant box installed on the same machine.

------

On fedora you may want to create /etc/polkit-1/rules.d/10.virt.rules and add
`
polkit.addRule(function(action, subject) {
polkit.log("action=" + action);
polkit.log("subject=" + subject);
var now = new Date();
polkit.log("now=" + now)
if ((action.id == "org.libvirt.unix.manage"
|| action.id == "org.libvirt.unix.monitor")

&& subject.isInGroup("~~your username group~~") // <--- change HERE

) {
return polkit.Result.YES;
}
return null;
});
``

This will help to prevent the system from asking the password.

---------------------------------------

Status

In development. It needs some tests. some more methods implementation.