Burrow

Introduction

I fed up with opening many separate Putty windows for so much SSH tunnels that I needed for my work, and instead I wanted to create a simple tool that has a single configuration for all of them and can be started with a single command and automatically reconnects whenever needed.

This simple application uses ssh2 and net to create SSH connections, and set up tunnels over them from a straightforward yaml or json configuration file.n It starts listening on configured ports on your machine and forwards incoming connections via the specified SSH connections, to your destination hosts. It automatically connects to the appropriate SSH server and initiates the port forward whenever a connection is made to one of the configured listening addresses, always trying to reconnect if existing connection is lost.

This is not an interactive app. You will not be able to manually enter passwords, and in fact why would you, if you have so much tunnels to start that you need burrow to set up your environment?

It requires private key based authentication either directly referencing the private key or using SSH authentication agent. Optionally, you may enter your passwords in the configuration, although if I were you I would never do that.

Requirements

• node.js -- v20.3.1 or newer

Installation

$ npm i -g @arpadegyed/burrow

Configuration

The configuration can be provided in json or yaml format according to your taste.

By default, the application will look for the configuration in your home directory with the .burrowConfig.yml, .burrowConfig.yaml, or .burrowConfig.json, however you may use the --burrow-config-path path/to/your/config.yml parameter to have it anywhere you like.

The configuration is hierarchical, first you define your SSH connections, and under each you provide your tunnel configurations to be set up over them.

The application will check the configuration at start, and stops on most problems that may prevent it from starting up correctly, however it has never been tested with all possible configurations. If your settings follow any of the examples below, it should work fine.

Sample configurations:

.burrowConfig.yml:

sshConnections: # list of your SSH connections
  - name: 'Dev server' # name your connection as you like, duplicate names not allowed!
    connectConfig: # SSH connection configuration (not all options listed, many of those may not even work properly!)
      username: 'someone' # username on target SSH server
      host: 'dev.local' # target SSH server name or IP address
      agent: 'pageant' # SSH authentication agent - Path to ssh-agent's UNIX socket,  on Windows use 'pageant' for authenticating with Pageant or (actual) path to a Cygwin UNIX socket.
      keepaliveInterval: 30000 # How often (in milliseconds) to send SSH-level keepalive packets to the server (in a similar way as OpenSSH's ServerAliveInterval config option). Set to 0 to disable. Default: 0
    tunnels: # list of your tunnels over current SSH connection
      - name: 'DEV DB' # name your tunnel as you like, duplicate names not allowed!
        forwardOptions:
          listenOptions: # if not defined, the listening address will be taken from the local TCP server
            host: 'localhost' # can be ommitted, defaults to localhost
            port: 5432 # the port to listen for connections
          destinationAddress: 'localhost' # destination host address and port that is accessible from the SSH server
          destinationPort: 5432 # port is mandatory
      - name: 'DEV Redis'
        forwardOptions:
          listenOptions:
            port: 9122
          # omitting destinationAddress will default to localhost 
          destinationPort: 9121
      - name: 'DEV App'
        forwardOptions:
          # not providing listenOptions will start listening on random local port
          destinationAddress: '10.0.45.44'
          destinationPort: 8080
  - name: 'UAT server'
    connectConfig:
      username: 'someone'
      host: 'uat.local'
      privateKeyPath: 'path/to/private.key' # you may use OpenSSH private keys directly, providing the path to them. Agent serves you better in my opinion, especially if you use passphrase. 
      passphrase: 'whatever' # passphrase for your private key
    tunnels:
      - name: 'UAT DB'
        forwardOptions:
          listenOptions:
            port: 5432
          destinationAddress: 'pg.uat.local'
          destinationPort: 5432
      - name: 'UAT app'
        forwardOptions:
          listenOptions:
            port: 8082
          destinationAddress: 'app.uat.local'
          destinationPort: 8080

.burrowConfig.json:

{
  "sshConnections": [
    {
      "name": "portal",
      "connectConfig": {
        "username": "someone",
        "host": "192.168.0.11",
        "agent": "pageant",
        "keepaliveInterval": 30000
      },
      "tunnels": [
        {
          "name": "ESB HTTPS",
          "forwardOptions": {
            "listenOptions": {
              "port": 11443
            },
            "destinationAddress": "esb.local",
            "destinationPort": 11443
          }
        },
        {
          "name": "ESB HTTP",
          "forwardOptions": {
            "listenOptions": {
              "port": 11080
            },
            "destinationAddress": "esb.local",
            "destinationPort": 11080
          }
        }
      ]
    },
    {
      "name": "Backend",
      "connectConfig": {
        "username": "someone",
        "host": "backend.local",
        "agent": "pageant",
        "keepaliveInterval": 30000
      },
      "tunnels": [
        {
          "name": "ORACLE",
          "forwardOptions": {
            "listenOptions": {
              "port": 1521
            },
            "destinationAddress": "oradb",
            "destinationPort": 1521
          }
        },
        {
          "name": "APP 1 HTTP",
          "forwardOptions": {
            "listenOptions": {
              "port": 8080
            },
            "destinationAddress": "app1.local",
            "destinationPort": 8080
          }
        },
        {
          "name": "APP 2 HTTP",
          "forwardOptions": {
            "listenOptions": {
              "port": 8081
            },
            "destinationAddress": "app2.local",
            "destinationPort": 8080
          }
        },
        {
          "name": "APP 3 HTTP",
          "forwardOptions": {
            "listenOptions": {
              "port": 8082
            },
            "destinationAddress": "app3.local",
            "destinationPort": 8080
          }
        },
        {
          "name": "LoadBalancer HTTPS",
          "forwardOptions": {
            "listenOptions": {
              "port": 1443
            },
            "destinationAddress": "app-lb.local",
            "destinationPort": 443
          }
        }
      ]
    }
  ]
}

How to run

# start all tunnels with configuration on default path (~/.burrowConfig.[yml|yaml|json])
$ burrow [all]

# start all tunnels with custom configuration and most debug logs
# log levels: 0 and below = off, 1 = fatal, 2 = error, 3 = warn, 4 = log (default), 5 = debug, 6 and above = verbose
$ burrow --burrow-config-path "path/to/your/config.yml" --log-level 5

# start a single tunnel from default configuration with all logging turned off
$ burrow single "DEV DB" --log-level 0

Use Ctrl+C to stop

License

Apache Licence 2.0.