Alinex SSH Connections: Readme

SSH connection handling with the ability to open tunnels for further communications and remote execution.

A SSH tunnel consists of an encrypted tunnel created through a SSH protocol connection. A SSH tunnel can be used to transfer unencrypted traffic over a network through an encrypted channel. This may also be used to bypass firewalls that prohibits or filter certain internet services. If users can connect to an external SSH server, they can create a SSH tunnel to forward a local port to a host and port reachable from the SSH server.

This module enables you to open and control such remote connections from your script and use them for execution or tunneling. The tunnels may also be used from external commands.

configurable ssh connections
pooling ssh connection
outgoing tunneling through SSH
dynamic port forwarding using SOCKSv5 proxy
cluster/group support

It is one of the modules of the Alinex Namespace following the code standards defined in the General Docs.

Read the complete documentation under https://alinex.github.io/node-ssh.

Install

The easiest way is to let npm add the module directly to your modules (from within you node modules directory):

npm install alinex-ssh --save

And update it to the latest version later:

npm update alinex-ssh --save

Always have a look at the latest changes.

Usage

This module has a very simple API, you can do three things:

Remote Connection

This is only a simple remote execution of a command line. To get more possibilities use the {@link alinex-exec} module which internaly calls this method with the correct commandline.

You can call the connect() Method with one of the following parametzers:

<String>                      # server or group from config
server: <String>              # server from config
server: <Connection>          # direct connection setup object
server: [<Connection>]        # list of alternative connections to same host
group: <String>               # group from config
group: [String]               # list of group servers from config
group: [<Connection>]         # group of direct connection setup
group: [[<Connection>]]       # group of alternative connections

Examples:

ssh = require 'alinex-ssh'
ssh.connect
  server:
    host: '65.25.98.25'
    port:  22
    username: 'root'
    #passphrase: 'mypass'
    privateKey: require('fs').readFileSync '/home/alex/.ssh/id_rsa'
    #localHostname: "Localost"
    #localUsername: "LocalUser"
    #readyTimeout: 20000
    keepaliveInterval: 1000
    #debug: true
  retry:
    times: 3
    intervall: 200
, (err, conn) ->
  console.log "ssh connection #{conn.name} opened"
  # wait 10 seconds, then close the tunnel
  setTimeout ->
    conn.end()
  , 10000

To close this connection you may use conn.end() to close if no longer used or conn.close() to close it also if other things are running on it. Or you may close all connections immediately with the global ssh.close().

This may also be called with a list of alternative server connections.

Configured

Or the short versions if configured in the configuration files needs only a name to reference the correct entry:

ssh = require 'alinex-ssh'
ssh.connect
  server: 'db'
  retry:
    times: 3
    intervall: 200
, (err, conn) ->
  console.log "ssh connection #{conn.name} opened"
  # wait 10 seconds, then close the tunnel
  setTimeout ->
    conn.close()
  , 10000

The retry part can also be kept away to use the defaults (from config).

The following is a short form, only possible if no special retry times are used:

ssh = require 'alinex-ssh'
ssh.connect 'db', (err, conn) ->
  console.log "ssh connection #{conn.name} opened"
  # wait 10 seconds, then close the tunnel
  setTimeout ->
    conn.close()
  , 10000

Cluster/Groups

Another possibility is to use a cluster or group to connect to the best server of it:

ssh = require 'alinex-ssh'
ssh.connect
  group: 'appcluster'
, (err, conn) ->
  console.log "ssh connection #{conn.name} opened"
  # wait 10 seconds, then close the tunnel
  setTimeout ->
    conn.close()
  , 10000

Alternatively you can give the group as an array of server names or configurations:

ssh = require 'alinex-ssh'
ssh.connect
  group: ['node1', 'node2', 'node3']
, (err, conn) ->
  console.log "ssh connection #{conn.name} opened"
  # wait 10 seconds, then close the tunnel
  setTimeout ->
    conn.close()
  , 10000

And also the short version is possible which will first try to use the given name as group else as server:

ssh = require 'alinex-ssh'
ssh.connect 'appcluster', (err, conn) ->
  console.log "ssh connection #{conn.name} opened"
  # wait 10 seconds, then close the tunnel
  setTimeout ->
    conn.done()
  , 10000

Tunneling

Simple forward tunnel

You can open a tunnel with:

ssh = require 'alinex-ssh'
ssh.tunnel
  server:
    host: '65.25.98.25'
    port:  22
    username: 'root'
    #passphrase: 'mypass'
    privateKey: require('fs').readFileSync '/home/alex/.ssh/id_rsa'
    #localHostname: "Localost"
    #localUsername: "LocalUser"
    #readyTimeout: 20000
    keepaliveInterval: 1000
    #debug: true
  tunnel:
    host: '172.30.0.11'
    port: 80
    #localhost: '127.0.0.1'
    #localPort: 8080
  retry:
    times: 3
    intervall: 200
, (err, tunnel) ->
  console.log "tunnel opened at #{tunnel.setup.host}:#{tunnel.setup.port}"
  # wait 10 seconds, then close the tunnel
  setTimeout ->
    tunnel.close()
  , 10000

And afterwards you may close it like shown above using tunnel.close() or (only if no longer used) or close all tunnels with:

ssh.close()

Or the really short versions if configured in the configuration files:

ssh = require 'alinex-ssh'
ssh.tunnel
  tunnel: 'intranet'
  retry:
    times: 3
    intervall: 200
, (err, conn) ->
  console.log "ssh connection #{conn.name} opened"
  # wait 10 seconds, then close the tunnel
  setTimeout ->
    tunnel.close()
  , 10000

ssh = require 'alinex-ssh'
ssh.tunnel 'intranet', (err, conn) ->
  console.log "ssh connection #{conn.name} opened"
  # wait 10 seconds, then close the tunnel
  setTimeout ->
    tunnel.close()
  , 10000

Dynamic SOCKSv5 Proxy

The following script shows how to make a dynamic 1:1 proxy using SOCKSv5. It's nearly the same, only the tunnel host and port are missing:

ssh = require 'alinex-ssh'
ssh.tunnel
  server:
    host: '65.25.98.25'
    port:  22
    username: 'root'
    #passphrase: 'mypass'
    privateKey: require('fs').readFileSync '/home/alex/.ssh/id_rsa'
    #localHostname: "Localost"
    #localUsername: "LocalUser"
    #readyTimeout: 20000
    keepaliveInterval: 1000
    #debug: true
, (err, tunnel) ->
  console.log "tunnel opened at #{tunnel.setup.host}:#{tunnel.setup.port}"
  # wait 10 seconds, then close the tunnel
  setTimeout ->
    tunnel.close()
  , 10000

Or the really short versions if configured in the configuration files:

ssh = require 'alinex-ssh'
ssh.tunnel 'db', (err, conn) ->
  console.log "ssh connection #{conn.name} opened"
  # wait 10 seconds, then close the tunnel
  setTimeout ->
    tunnel.close()
  , 10000

Cluster/Group

Like in the use of connections you may use cluster or group names within the tunneling, too. This means that the tunnel will be made through the best working host.

ssh = require 'alinex-ssh'
ssh.tunnel
  group: 'dmz'
  tunnel:
    host: '172.30.0.11'
    port: 80
  retry:
    times: 3
    intervall: 200
, (err, conn) ->
  console.log "ssh connection #{conn.name} opened"
  # wait 10 seconds, then close the tunnel
  setTimeout ->
    tunnel.close()
  , 10000

And if you use a preconfigured tunnel you may use the group reference name within the tunnel's remote setting like the server name.

Configuration files

To use configuration files you also need to setup and initialize this before using it:

ssh = require 'alinex-ssh'
ssh.setup (err) ->
  ssh.init (err) ->
    # do your work

See the {@link src/configSchema.coffee} for a detailed information about it's possibilities. And then put your own settings in external files like described at {@link alinex-config}:

/ssh/server.yaml - contains named setup of ssh connections
/ssh/group.yaml - cluster/group definition
/ssh/tunnel.yaml - set the tunnel configuration with name

But you may also directly give your setup to the methods above.

Remote Execution

To do this you have to use the {@link alinex-exec} module which internally connects using this and also uses the same configuration files.

Tips and Tricks

Execute on whole Group

This may be done easily if you step over the configured list of servers of a group. Mostly you have a cluster there and want to take the action on each of them but seriously to don't disturb your app users.

config = require 'alinex-config'
async.eachSeries config.get('/ssh/group/appcluster'), (server, cb) ->
  # do something with this server like remote execution
, (err) ->
  # check for problems

Debugging

If you have any problems with the tunnel you may always run it with debugging by only setting the DEBUG environment variable like:

DEBUG=ssh myprog-usingssh         # general ssh info
DEBUG=ssh:tunnel myprog-usingssh  # tunnel information
DEBUG=ssh:data myprog-usingssh    # output data send connection
DEBUG=ssh:debug myprog-usingssh   # output debug level (needs debug: true in server settings)
DEBUG=ssh* myprog-usingssh        # output alltogether

To get even more information you may also set the debug flag to true in the setup of your ssh tunnel and enable DEBUG=ssh:debug.

If you enable debugging of ssh the given configuration will also be validated.

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

alinex/node-ssh