open-ssh-tunnel

Easy ssh tunneling function based on ssh2 library

Inspired by tunnel-ssh, but with simplified, more modern code.

Installation

npm install --save open-ssh-tunnel

Usage

  const openSshTunnel = require('open-ssh-tunnel');
  async function openATunnel() {
    const server = await openSshTunnel({
      host: 'your.server.address.com',
      username: 'you',
      password: 'secret',
      srcPort: 3306,
      srcAddr: '127.0.0.1',
      dstPort: 3306,
      dstAddr: '127.0.0.1',
      readyTimeout: 1000,
      forwardTimeout: 1000,
      localPort: 3306,
      localAddr: '127.0.0.1'
    });

    // you can now connect to your
    // forwarded tcp port!

    // later, when you want to close the tunnel
    server.close();
  }

Example

╭───────────────╮      ╭─────────────────╮      ╭─────────╮      ╭─────────╮
│ Mongo         │      │ open-ssh-tunnel │      │ SSH     │      │ Mongo   │
│ client        │ <--> │                 │ <--> │ server  │ <--> │ server  │
│ 192.168.1.1   │      │ 192.168.1.2     │      │ 10.0.0.2│      │ 10.0.0.1│
│               │      │                 │      │         │      │         │
╰───────────────╯      ╰─────────────────╯      ╰─────────╯      ╰─────────╯

In scenario where you want to connect to mongo that runs on a remote host, you should provide the following configuration.

{
    destPort: 27017,
    destAddr: '10.0.0.1',
    host: '10.0.0.2',
    port: 22,
    localAddr: 27018,
    localPort: '192.168.1.2',
    srcAddr: '192.168.1.1',
    srcPort: 27019,
    ...
}

Note that you have to provide localAddr when you need to make the tunnel visible to other hosts in your LAN.

srcAddr and srcPort, when provided, should be the network address of a client host connecting to your SSH tunnel local endpoint. If you do not need them you can provide any value for the arguments.

API

The module exports openSshTunnel function. It return a promise that resolve to a node net server instance if tunnel is opened, otherwise is rejected with an error.

Options

srcIP and srcPort as the originating address and port and dstIP and dstPort as the remote destination address and port. These are options passed to ssh2 Client.forwardOut method.
forwardTimeout - How many millisecond to wait before reject with a timeout error.
localAddr and localPort are the address and port of the local endpoint of the tunnel on your machine. They are passed to net server connect method.
All other options are passed to ssh2 Client.connect method.

electron-tunnel - Awesome Electron app to manage your ssh tunnels - powered by this module.

License

The MIT License (MIT)

parro-it / open-ssh-tunnel

readme