system-ssh

A wrapper for system ssh with SSH2 interface.

Table of Contents

• Requirements
• Installation
• Client examples
  • Execute 'uptime' on a server
  • Send a raw HTTP request to port 80 on the server
  • Connection hopping
• Client events
• Client methods

Requirements

• node.js -- v10.16.0 or newer
  • node v12.0.0 or newer for Ed25519 key support

Installation

npm install system-ssh

Client examples

Execute 'uptime' on a server

const { Client } = require('system-ssh');

const conn = new Client();
conn.on('ready', () => {
  console.log('Client :: ready');
  conn.exec('uptime', (err, stream) => {
    if (err) throw err;
    stream.on('close', (code, signal) => {
      console.log('Stream :: close :: code: ' + code + ', signal: ' + signal);
      conn.end();
    }).on('data', (data) => {
      console.log('STDOUT: ' + data);
    }).stderr.on('data', (data) => {
      console.log('STDERR: ' + data);
    });
  });
}).connect({
  host: '192.168.100.100',
  port: 22,
  username: 'test',
  identityFile: '/path/to/my/key'
});

// example output:
// Client :: ready
// STDOUT:  13:31:36 up 118 days,  4:02,  1 user,  load average: 1,82, 1,32, 1,34
//
// Stream :: close :: code: 0, signal: null

Send a raw HTTP request to port 80 on the server

const { Client } = require('system-ssh');

const conn = new Client();
conn.on('ready', () => {
  console.log('Client :: ready');
  conn.forwardOut('192.168.100.102', 8000, '127.0.0.1', 80, (err, stream) => {
    if (err) throw err;
    stream.on('close', () => {
      console.log('TCP :: CLOSED');
      conn.end();
    }).on('data', (data) => {
      console.log('TCP :: DATA: ' + data);
    }).end([
      'HEAD / HTTP/1.1',
      'User-Agent: curl/7.27.0',
      'Host: 127.0.0.1',
      'Accept: */*',
      'Connection: close',
      '',
      ''
    ].join('\r\n'));
  });
}).connect({
  host: '192.168.100.100',
  port: 22,
  username: 'test',
  identityFile: '/path/to/my/key'
});

// example output:
// Client :: ready
// TCP :: DATA: HTTP/1.1 200 OK
// Server: nginx/1.14.1
// Date: Tue, 28 Feb 2023 14:45:40 GMT
// Content-Type: text/html
// Content-Length: 871
// Last-Modified: Tue, 19 Jul 2022 15:07:04 GMT
// Connection: close
// ETag: "62d6c898-367"
// Accept-Ranges: bytes
//
//
//TCP :: CLOSED

Connection hopping

const { Client } = require('system-ssh');

const conn = new Client();
conn.on('ready', () => {
  console.log('Client :: ready');
  conn.exec('uptime', (err, stream) => {
    if (err) throw err;
    stream.on('close', (code, signal) => {
      console.log('Stream :: close :: code: ' + code + ', signal: ' + signal);
      conn.end();
    }).on('data', (data) => {
      console.log('STDOUT: ' + data);
    }).stderr.on('data', (data) => {
      console.log('STDERR: ' + data);
    });
  });
}).connect({
  host: '192.168.100.100',
  port: 22,
  username: 'test',
  identityFile: '/path/to/my/key',
  jumpHosts: '192.168.100.101'  
});

// example output:
// Client :: ready
// STDOUT:  21:57:11 up 344 days,  8:09,  7 users,  load average: 0,42, 0,38, 0,29
//
// Stream :: close :: code: 0, signal: null

Client events

• close(code, signal) - master process was closed.

• error(< Error >err) - an error occurred in master process.

• ready() - master process is ready.

Client methods

• (constructor)() - Creates and returns a new Client instance.

• connect(< object >config) - (void) - Attempts a connection to a server using the information given in config:

  • forceIPv4 - boolean - Only connect via resolved IPv4 address for host. Default: false

  • forceIPv6 - boolean - Only connect via resolved IPv6 address for host. Default: false

  • host - string - Hostname or IP address of the server. Default: 'localhost'

  • port - integer - Port number of the server. Default: 22

  • identityFile - string - Path to a private key file. Default: (none)

  • username - string - Username for authentication. Default: (none)

  • options - string[] - Array of ssh options, see ssh_config(5). Default: (none)

  • jumpHosts - string - Comma separated list of jump hosts. Default: (none)

• end() - (void) - Disconnects the client.

• exec(< string >command[, < object >options], < function >callback) - (void) - Executes command on the server. callback has 2 parameters: < Error >err, < Channel >stream. options - process spawn options.

• forwardOut(< string >srcIP, < integer >srcPort, < string >dstIP, < integer >dstPort, < function >callback) - (void) - Open a connection with srcIP and srcPort as the originating address and port and dstIP and dstPort as the remote destination address and port. callback has 2 parameters: < Error >err, < Channel >stream.

• forwardOutLocalSocket(< string >localSocket, < string >dstIP, < integer >dstPort, < function >callback) - (void) - Connections to the given Unix socket localSocket on the local (client) host are to be forwarded to the given host dstIP and port dstPort on the remote side. callback has 2 parameters: < Error >err, < Channel >stream.