Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 8 additions & 9 deletions .env-example
Original file line number Diff line number Diff line change
@@ -1,19 +1,18 @@
# Live tests and provisioning target: src (development), lib (release build),
# baseline (regression fixture), or a path relative to the repository root.
SSH2SHELL_MODULE=src

# Primary host (server1)
HOST=192.168.44.10
PORT=22
USER_NAME=tester
PASSWORD=password

# Private key authentication (test/live/private_key.js) and hop auth
# Private key authentication (test/live/private_key.js) and `forwardOut` hops.
# Hops use the runner's local key, so this is the only key path the tests need.
PRIVATE_KEY_PATH=test/certs/test_ed25519
KEY_PASSPHRASE=

# Path to the private key as it exists on the jump host(s), used by nested
# `ssh -i` hops. Override these when the key is installed elsewhere or under a
# different name. They must be absolute paths on the jump host.
HOP_KEY_PATH=/home/tester/.ssh/id_ed25519
HOP2_KEY_PATH=/home/tester/.ssh/id_ed25519

# Host fingerprint verification (test/live/fingerprint.js)
# Leave empty to print the hash and accept the first connection, then pin it.
EXPECTED_HOST_HASH=
Expand All @@ -33,8 +32,8 @@ NOPASSWD_USER=nopasswd
NOPASSWD_PASSWORD=nopasswdpassword

# Nested, tunnelled, and chained hosts
# The test key authenticates these hosts. The *_PASSWORD values are only
# needed if you switch a test back to password authentication.
# The local test key authenticates these hosts through `forwardOut`. The
# *_PASSWORD values are only needed if you switch a test to password auth.
SERVER2_HOST=192.168.44.11
SERVER2_PORT=22
SERVER2_USER_NAME=tester
Expand Down
109 changes: 109 additions & 0 deletions .github/workflows/live.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
name: Live tests

on:
workflow_call:
inputs:
ref:
description: Git ref to test
required: false
type: string
push:
branches:
- master
pull_request:
workflow_dispatch:
schedule:
- cron: '17 3 * * *'

permissions:
contents: read

concurrency:
group: live-${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true

jobs:
live:
name: Live suite
runs-on: ubuntu-latest
timeout-minutes: 30

steps:
- name: Check out
uses: actions/checkout@v4
with:
ref: ${{ inputs.ref || github.ref }}

- name: Set up Node
uses: actions/setup-node@v4
with:
node-version: 24.x
cache: npm

- name: Install
run: npm ci

# The private key is gitignored, so each run gets a throwaway pair. The
# setup script installs the public half for the test users.
- name: Generate throwaway SSH key
run: ssh-keygen -q -t ed25519 -N "" -C ssh2shell-ci -f "$RUNNER_TEMP/test_ed25519"

- name: Start test hosts
run: sudo bash test/ci/setup-live-hosts.sh "$RUNNER_TEMP/test_ed25519.pub"

# The runner image runs its own sshd on 0.0.0.0:22, so the test hosts use
# 2222 (the setup script's default). Keep these in sync with
# test/ci/setup-live-hosts.sh if LIVE_SSH_PORT is changed.
- name: Run live suite
env:
SSH2SHELL_MODULE: src
HOST: 127.0.0.10
PORT: '2222'
USER_NAME: tester
PASSWORD: password
PRIVATE_KEY_PATH: ${{ runner.temp }}/test_ed25519
KEY_PASSPHRASE: ''
EXPECTED_HOST_HASH: ''
SECOND_USER: suuser
SECOND_USER_PASSWORD: secondpassword
NOPASSWD_USER: nopasswd
NOPASSWD_PASSWORD: nopasswdpassword
KBD_USER: kbduser
KBD_PASSWORD: kbdpassword
KBD_HOST: 127.0.0.10
KBD_PORT: '2222'
SERVER1_HOST: 127.0.0.10
SERVER1_PORT: '2222'
SERVER1_USER_NAME: tester
SERVER1_PASSWORD: password
SERVER2_HOST: 127.0.0.11
SERVER2_PORT: '2222'
SERVER2_USER_NAME: tester
SERVER2_PASSWORD: password
SERVER3_HOST: 127.0.0.12
SERVER3_PORT: '2222'
SERVER3_USER_NAME: tester
SERVER3_PASSWORD: password
run: npm run test:live:all

# sshd logs are root-owned, and upload-artifact runs as the runner user.
# Copy them into the workspace so the artifact has one readable root.
- name: Collect live logs
if: always()
run: |
mkdir -p test/logs/sshd
sudo cp /var/log/ssh2shell/*.log test/logs/sshd/ 2>/dev/null || true
sudo chown -R "$(id -u):$(id -g)" test/logs

- name: Upload live logs
if: always()
uses: actions/upload-artifact@v4
with:
name: live-logs
path: test/logs
if-no-files-found: ignore
retention-days: 7

- name: Stop test hosts
if: always()
run: sudo bash test/ci/stop-live-hosts.sh
7 changes: 7 additions & 0 deletions .github/workflows/publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,15 @@ concurrency:
cancel-in-progress: false

jobs:
live:
name: Live suite
uses: ./.github/workflows/live.yml
with:
ref: ${{ inputs.ref || github.ref }}

publish:
name: Publish ${{ inputs.ref || github.ref_name }}
needs: live
runs-on: ubuntu-latest
steps:
- name: Check out
Expand Down
76 changes: 76 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
# Changelog

All notable changes to this project are recorded here. The format follows
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
[semantic versioning](https://semver.org/spec/v2.0.0.html).

Releases before `4.0.0` are recorded as git tags and GitHub Releases.

## [Unreleased]

## [4.0.0] - 2026-11-15

### Breaking changes

- **Host hops use `ssh2` `forwardOut` channels.** The nested `ssh` command path
is gone, so a jump host no longer needs an `ssh` client, a shell, or a copy of
your key. `server.ssh` and its options are removed: use `ssh2` connection
options instead (`algorithms` replaces `cipherSpec` / `macSpec`, and
`forceIPv4` / `forceIPv6` replace `forceAddressType`). `exitCommands` is
removed with the command path.
- **`host.msg` is renamed to `host.onMsg`.** The Hubot-era `msg: { send: fn }`
shape is no longer mapped.
- **`server.hashMethod` is removed.** Use `hostHash` or `hostVerifier`.
- **`sshObj.stop` is removed.** Use `abort`.
- **Host `idleTime` and `dataIdleTime` are removed.** Use `idleTimeOut` and
`dataIdleTimeOut`. The instance-level `SSH.idleTime` and `SSH.dataIdleTime`
remain.
- **`commandStartTimeout` and `details.noOutput` are removed.** The command idle
timer is always armed when a command is written, so a silent command times
out. A command that returns to a prompt without output is a normal
completion.
- **`passphrasePrompt` is removed.** Only `passwordPrompt` remains.
- **An empty host list throws.** `new SSH2Shell([])`, `null`, and `undefined`
throw a `TypeError` instead of starting a run with no hosts.
- **Host objects are mutated during a run.** `commands` is consumed,
`sessionText` accumulates, and flags such as `pwSent` and `sudoFailed` are
updated. Create a fresh object, or clone it, before reusing it with another
instance.

### Added

- Depth-first hop traversal with sibling hosts. Each hop is a real `ssh2`
connection opened through the parent's `forwardOut` channel, and it is
verified with the same `hostHash` / `hostVerifier` contract as a primary.
- Contained hop failures. A failed hop emits `error` with type `Hop`, skips its
commands and unstarted descendants, and the parent continues with its
remaining hosts. A failed primary is finalized and the next primary runs.
- Per-hop `connectedMessage`, `readyMessage`, and `closedMessage`.
- Provisioning `--print-config` and environment-source logging (development
tooling).

### Changed

- The command idle timer is armed when a command is written, not after the
first output, so a command that never produces output still times out.
- Responses are sliced after the last echoed command, which removes earlier
session noise and the garbled-buffer workaround.
- `command` and `_buffer` are record-scoped and restored when backing out of a
hop, so the parent resumes its own command state.
- Host config no longer receives library state: default handlers are resolved
per record instead of being written into the host object, and
`applyHostDefaults` no longer writes `server.hashKey`.

### Development

- Added `test/live/host_traversal.js` and `test/live/host_faults.js` as the
acceptance tests for hop traversal and fault containment.
- Added `SSH2SHELL_MODULE` (`src`, `lib`, `baseline`, or a repository-relative
path) to select the build under test for live tests and provisioning.
- Rewrote the provisioning script around the current host API and a documented
`PROVISION_*` environment contract. Re-provisioning removes the 3.x
`~/.ssh/id_ed25519` copies that were only needed by nested `ssh -i` hops.
- `ssh2Client` is now `_ssh2Client` and is documented as an internal test seam.

[Unreleased]: https://github.com/cmp-202/ssh2shell/compare/v4.0.0...HEAD
[4.0.0]: https://github.com/cmp-202/ssh2shell/compare/v3.3.0...v4.0.0
Loading
Loading