# ssh-pool

> Run remote commands over a pool of server using SSH.

Latest version **5.3.0** (published 2020-03-18) · MIT license · 0 weekly downloads

## Install

```sh
npm install ssh-pool
pnpm add ssh-pool
yarn add ssh-pool
bun add ssh-pool
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 5.3.0 |
| Published | 2020-03-18 |
| First published | 2014-12-31 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=6 |
| Dependencies | 3 |
| Unpacked size | 41.4 KB |
| Known vulnerabilities | 0 (+2 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 5293 |
| Author | Greg Bergé |
| Maintainers | neoziro, timkelty |
| Keywords | shipit, automation, deployment, ssh |

## Links

- npm: https://www.npmjs.com/package/ssh-pool
- Repository: https://github.com/shipitjs/shipit/tree/master/packages/shipit-deploy
- npm.io page: https://npm.io/package/ssh-pool

## Dependencies (3)

- [tmp](https://npm.io/package/tmp.md) ^0.1.0
- [which](https://npm.io/package/which.md) ^1.3.1
- [stream-line-wrapper](https://npm.io/package/stream-line-wrapper.md) ^0.1.1

## Recent versions

- 5.3.0 (latest) — 2020-03-18
- 5.2.0 — 2020-03-07
- 5.1.0 — 2019-08-28
- 5.0.0 — 2019-07-15
- 4.1.2 — 2018-11-04
- 4.1.0 — 2018-04-27
- 4.0.2 — 2018-03-25
- 4.0.0 — 2018-03-17
- 1.5.0 — 2017-06-27
- 1.4.2 — 2017-06-27
- 1.4.1 — 2016-11-15
- 1.4.0 — 2016-11-13
- 1.3.0 — 2015-04-06
- 1.2.1 — 2015-03-20
- 1.2.0 — 2015-02-23
- … 3 more at https://npm.io/package/ssh-pool/versions

## README

# ssh-pool

[![Build Status][build-badge]][build]
[![version][version-badge]][package]
[![MIT License][license-badge]][license]

Run remote commands over a pool of server using SSH.

```sh
npm install ssh-pool
```

## Usage

```js
import { ConnectionPool } from 'ssh-pool'

const pool = new ConnectionPool(['user@server1', 'user@server2'])

async function run() {
  const results = await pool.run('hostname')
  console.log(results[0].stdout) // 'server1'
  console.log(results[1].stdout) // 'server2'
}
```

### new Connection(options)

Create a new connection to run command on a remote server.

**Parameters:**

```
@param {object} options Options
@param {string|object} options.remote Remote
@param {Stream} [options.stdout] Stdout stream
@param {Stream} [options.stderr] Stderr stream
@param {string} [options.key] SSH key
@param {function} [options.log] Log method
@param {boolean} [options.asUser] Use a custom user to run command
@param {number} [options.verbosityLevel] SSH verbosity level: 0 (none), 1 (-v), 2 (-vv), 3+ (-vvv)
```

The remote can use the shorthand syntax or an object:

```js
// You specify user and host
new Connection({ remote: 'user@localhost' })

// You can specify a custom SSH port
new Connection({ remote: 'user@localhost:4000' })

// You can also define remote using an object
new Connection({
  remote: {
    user: 'user',
    host: 'localhost',
    port: 4000,
  },
})

// When defined as an object you can add extra ssh parameters
new Connection({
  remote: {
    user: 'user',
    host: 'localhost',
    port: 4000,
    extraSshOptions: {
      ServerAliveInterval: '30',
    }
  },
})
```

The log method is used to log output directly:

```js
import { Connection } from 'ssh-pool'

const connection = new Connection({
  remote: 'localhost',
  log: (...args) => console.log(...args),
})

connection.run('pwd')

// Will output:
// Running "pwd" on host "localhost".
// @localhost /my/directory
```

### connection.run(command, [options])

Run a command on the remote server, you can specify custom `childProcess.exec` options.

**Parameters:**

```
@param {string} command Command to run
@param {object} [options] Options
@param {boolean} [options.tty] Force a TTY allocation.
@returns {ExecResult}
@throws {ExecError}
```

```js
// Run "ls" command on a remote server
connection.run('ls').then(res => {
  console.log(res.stdout) // file1 file2 file3
})
```

### connection.copyToRemote(src, dest, [options])

Copy a file or a directory from local to a remote server, you can specify custom `childProcess.exec` options. It uses rsync under the hood.

**Parameters:**

```
* @param {string} src Source
* @param {string} dest Destination
* @param {object} [options] Options
* @param {string[]} [options.ignores] Specify a list of files to ignore.
* @param {string[]|string} [options.rsync] Specify a set of rsync arguments.
* @returns {ExecResult}
* @throws {ExecError}
```

```js
// Copy a local file to a remote file using Rsync
connection.copyToRemote('./localfile', '/remote-file').then(() => {
  console.log('File copied!')
})
```

### connection.copyFromRemote(src, dest, [options])

Copy a file or a directory from a remote server to local, you can specify custom `childProcess.exec` options. It uses rsync under the hood.

**Parameters:**

```
* @param {string} src Source
* @param {string} dest Destination
* @param {object} [options] Options
* @param {string[]} [options.ignores] Specify a list of files to ignore.
* @param {string[]|string} [options.rsync] Specify a set of rsync arguments.
* @returns {ExecResult}
* @throws {ExecError}
```

```js
// Copy a remote file to a local file using Rsync
connection.copyFromRemote('/remote-file', './local-file').then(() => {
  console.log('File copied!')
})
```

### new ConnectionPool(connections, [options])

Create a new pool of connections and custom options for all connections.
You can use either short syntax or connections to create a pool.

```js
import { Connection, ConnectionPool } from 'ssh-pool'

// Use shorthand.
const pool = new ConnectionPool(['server1', 'server2'])

// Use previously created connections.
const connection1 = new Connection({ remote: 'server1' })
const connection2 = new Connection({ remote: 'server2' })
const pool = new ConnectionPool([connection1, connection2])
```

Connection Pool accepts exactly the same methods as Connection. It runs commands in parallel on each server defined in the pool. You get an array of results.

### isRsyncSupported()

Test if rsync is supported on the local machine.

```js
import { isRsyncSupported } from 'ssh-pool'

isRsyncSupported().then(supported => {
  if (supported) {
    console.log('Rsync is supported!')
  } else {
    console.log('Rsync is not supported!')
  }
})
```

### exec(cmd, options, childModifier)

Execute a command and return an object containing `{ child, stdout, stderr }`.

```js
import { exec } from 'ssh-pool'

exec('echo "hello"')
  .then(({ stdout }) => console.log(stdout))
  .catch(({ stderr, stdout }) => console.error(stderr))
```

## License

MIT

[build-badge]: https://img.shields.io/travis/shipitjs/shipit.svg?style=flat-square
[build]: https://travis-ci.org/shipitjs/shipit
[version-badge]: https://img.shields.io/npm/v/ssh-pool.svg?style=flat-square
[package]: https://www.npmjs.com/package/ssh-pool
[license-badge]: https://img.shields.io/npm/l/ssh-pool.svg?style=flat-square
[license]: https://github.com/shipitjs/shipit/blob/master/LICENSE

---
_Source: https://npm.io/package/ssh-pool · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._