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

API

• 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

Examples

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

    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);
    });

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

    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();
        });
    });

Execute a series of command on remote server and returns their output.

Arguments

• server - An object of ssh server credentials.
• cmds - An array of commands line to execute on remote.
• onCmdCplt(command, response, server) - A callback called on command line completion.
  • command the completed command line.
  • response the completed command line response.
  • server An ssh server credentials object.
• onDone(sessionText, sshObj) - A callback called on session completion.
  • err an Error.
  • sessionText a String.
  • sshObj An ssh Client object.

Examples

    var SSH2Utils = require('ssh2-utils');
    var ssh = new SSH2Utils();
    
    var server = {host: "localhost", username:"user", password:"pwd" };
    
    ssh.runMultiple(server, ['ls','time'], function(sessionText, sshObj){
        console.log(sessionText);
    });

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

    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);
    });

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

    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);
    });

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

    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);
    });

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

    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);
    });

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

    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);
    });

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

    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.