SkillAgentSearch skills...

Bssh

A high-performance parallel SSH command execution tool for cluster management

GenerateConvertImprove

Install / Use

/learn @lablup/Bssh
About this skill

Quality Score

0/100

Supported Platforms

Universal

Tags

clissh

README

bssh - Broadcast SSH

Crates.io version Crates.io downloads GitHub Downloads CI dependency status

A high-performance SSH client with SSH-compatible syntax for both single-host and parallel cluster operations, built with Rust and russh.

Developed and maintained as part of the Backend.AI project.

Features

  • SSH Compatibility: Drop-in replacement for SSH with compatible command-line syntax
  • Port Forwarding: Full support for local (-L), remote (-R), and dynamic (-D) SSH port forwarding
  • Jump Host Support: Connect through bastion hosts using OpenSSH ProxyJump syntax (-J)
  • Parallel Execution: Execute commands across multiple nodes simultaneously
  • Hostlist Expressions: pdsh-style range expansion (node[1-5], rack[1-2]-node[1-3]) for compact host specification
  • Fail-Fast Mode: Stop immediately on first failure with -k flag (pdsh compatible)
  • Interactive Terminal UI (TUI): Real-time monitoring with 4 view modes (Summary/Detail/Split/Diff) for multi-node operations
  • Cluster Management: Define and manage node clusters via configuration files
  • Progress Tracking: Real-time progress indicators with smart detection (percentages, fractions, apt/dpkg)
  • Flexible Authentication: Support for SSH keys, SSH agent, password authentication, and encrypted key passphrases
  • Host Key Verification: Secure host key checking with known_hosts support
  • Cross-Platform: Works on Linux and macOS
  • Output Management: Multiple output modes (TUI, stream, file, normal) with auto-detection
  • Interactive Mode: Interactive shell sessions with single-node or multiplexed multi-node support
  • SSH Config Caching: High-performance caching of SSH configurations with TTL and file modification detection
  • Configurable Timeouts: Set both connection timeout (--connect-timeout) and command execution timeout (--timeout) with support for unlimited execution
  • SSH Keepalive: Configurable keepalive settings (--server-alive-interval, --server-alive-count-max) to prevent idle connection timeouts

Installation

Install via Homebrew (macOS/Linux)

The easiest way to install bssh on macOS and Linux is through Homebrew:

brew tap lablup/tap
brew install bssh

Install via Ubuntu PPA

For Ubuntu users, bssh is available through the official PPA:

# Add the PPA repository
sudo add-apt-repository ppa:lablup/backend-ai
sudo apt update

# Install bssh
sudo apt install bssh

Install via Debian Package

For Debian and other Debian-based distributions, download the .deb package from the releases page:

# Download the latest .deb package (replace VERSION with the actual version)
wget https://github.com/lablup/bssh/releases/download/vVERSION/bssh_VERSION_OS_ARCH.deb
# Example: bssh_0.4.0_ubuntu24.04.noble_amd64.deb

# Install the package
sudo dpkg -i bssh_VERSION_OS_ARCH.deb

# If there are dependency issues, fix them with:
sudo apt-get install -f

Download Pre-built Binary

Download the latest release from the GitHub releases page:

  1. Go to https://github.com/lablup/bssh/releases
  2. Download the appropriate binary for your platform
  3. Extract the archive and place the binary in your $PATH

Install from Cargo

cargo build --release
sudo cp target/release/bssh /usr/local/bin/

Quick Start

SSH-Compatible Mode (Single Host)

# Connect to a host (just like SSH!)
bssh user@hostname

# Execute a command
bssh user@hostname "uptime"

# With specific port and key
bssh -p 2222 -i ~/.ssh/key.pem admin@server.com

# Using SSH options
bssh -o StrictHostKeyChecking=no user@host

# Query SSH capabilities
bssh -Q cipher

PTY Session Escape Sequences:

Like OpenSSH, bssh supports escape sequences in PTY sessions. These must be typed at the beginning of a line (after pressing Enter):

| Escape | Description | |--------|-------------| | ~. | Disconnect from the remote host |

Port Forwarding

# Local port forwarding (-L)
# Forward local port 8080 to example.com:80 via SSH
bssh -L 8080:example.com:80 user@host

# Remote port forwarding (-R)  
# Forward remote port 8080 to localhost:80
bssh -R 8080:localhost:80 user@host

# Dynamic port forwarding / SOCKS proxy (-D)
# Create SOCKS5 proxy on local port 1080
bssh -D 1080 user@host

# Multiple port forwards
bssh -L 3306:db:3306 -R 80:web:80 -D 1080 user@host

# Bind to specific address
bssh -L 127.0.0.1:8080:web:80 user@host           # Local only
bssh -L *:8080:web:80 user@host                   # All interfaces

# SOCKS4 proxy (specify version)
bssh -D 1080/4 user@host                          # SOCKS4
bssh -D *:1080/5 user@host                        # SOCKS5 on all interfaces

# Port forwarding with command execution
bssh -L 5432:postgres:5432 user@host "psql -h localhost"

# Port forwarding with cluster operations
bssh -C production -L 8080:internal:80 "curl http://localhost:8080"

Jump Host Support (ProxyJump)

# Connect through a single jump host (bastion)
bssh -J jump@bastion.example.com user@internal-server

# Multiple jump hosts (connection chain)
bssh -J "jump1@proxy1,jump2@proxy2" user@final-destination

# Jump host with custom port
bssh -J admin@bastion:2222 user@internal-host

# IPv6 jump host
bssh -J "[2001:db8::1]:22" user@destination

# Combine with cluster operations
bssh -J bastion.example.com -C production "uptime"

# File transfer through jump host
bssh -J bastion.example.com -H internal-server upload app.tar.gz /opt/
bssh -J admin@bastion:2222 -C production download /etc/config ./backups/

# Interactive mode through jump hosts
bssh -J bastion.example.com user@internal-server
bssh -J "jump1,jump2" -C production interactive

# Multi-hop with file transfer
bssh -J "bastion1,bastion2,bastion3" -H target upload -r ./app/ /opt/app/

Multi-Server Mode (Cluster Operations)

# Execute commands on multiple hosts (automatic command execution)
bssh -H "user1@host1.com,user2@host2.com:2222" "uptime"

# Using cluster from config
bssh -C production "df -h"

# Hostlist expressions (pdsh-style range expansion)
bssh -H "node[1-5]" "uptime"                       # node1, node2, node3, node4, node5
bssh -H "node[01-05]" "df -h"                      # Zero-padded: node01, node02, ...
bssh -H "node[1,3,5]" "ps aux"                     # Specific values: node1, node3, node5
bssh -H "rack[1-2]-node[1-3]" "uptime"             # Cartesian product: 6 hosts
bssh -H "web[1-3].example.com" "nginx -v"          # With domain suffix
bssh -H "admin@db[01-03]:5432" "psql --version"    # With user and port
bssh -H "^/etc/hosts.cluster" "uptime"             # Read hosts from file

# Filter specific hosts with pattern matching
bssh -H "web1,web2,db1,db2" -f "web*" "systemctl status nginx"
bssh -C production -f "db*" "pg_dump --version"
bssh -H "node[1-10]" -f "node[1-5]" "uptime"       # Filter with hostlist expression

# Exclude specific hosts from execution
bssh -H "node1,node2,node3" --exclude "node2" "uptime"
bssh -C production --exclude "db*" "systemctl restart nginx"
bssh -H "node[1-10]" --exclude "node[3-5]" "uptime" # Exclude with hostlist expression

# With custom SSH key
bssh -C staging -i ~/.ssh/custom_key "systemctl status nginx"

# Use SSH agent for authentication
bssh -A -C production "systemctl status nginx"

# Use password authentication (will prompt for password)
bssh --password -H "user@host.com" "uptime"

# Use sudo password for privileged commands (prompts securely)
bssh -S -C production "sudo apt update && sudo apt upgrade -y"

# Combine sudo password with SSH agent authentication
bssh -A -S -C production "sudo systemctl restart nginx"

# Use encrypted SSH key (will prompt for passphrase)
bssh -i ~/.ssh/encrypted_key -C production "df -h"

# Limit parallel connections
bssh -C production --parallel 5 "apt update"

# Set command timeout (10 seconds)
bssh -C production --timeout 10 "quick-check"

# No timeout (unlimited execution time)
bssh -C staging --timeout 0 "long-running-backup"

# Set connection timeout (default: 30 seconds)
bssh -C production --connect-timeout 10 "uptime"

# Different timeouts for connection and command
bssh -C production --connect-timeout 5 --timeout 600 "long-running-job"

# Configure SSH keepalive (prevent idle connection timeouts)
bssh -C production --server-alive-interval 30 "long-running-job"

# Disable keepalive (set interval to 0)
bssh -C production --server-alive-interval 0 "quick-job"

# Keepalive with custom max retries (default: 3)
bssh -C production --server-alive-interval 60 --server-alive-count-max 5 "long-running-job"

# Fail-fast mode: stop immediately on any failure (pdsh -k compatible)
bssh -k -H "web1,web2,web3" "deploy.sh"
bssh --fail-fast -C production "critical-script.sh"

# Combine fail-fast with require-all-success for critical operations
bssh -k --require-all-success -C production "service-restart.sh"

Output Modes

bssh automatically selects the best output mode based on your environment:

TUI Mode (Default in Terminals)

Interactive Terminal UI with real-time monitoring - automatically enabled when running in an interactive terminal.

# TUI mode automatically activates for multi-node commands
bssh -C production "apt-get update"

# Features:
# - Summary view: All nodes at a glance with progress bars
# - Detail view: Full output from specific node with scrolling
# - Split view: Monitor 2-4 nodes simultaneously

lablup

View profile

View on GitHub
GitHub Stars24
CategoryDevelopment
Updated1mo ago
Forks1
lablup/bssh

Languages

Rust

Security Score

95/100

Audited on Feb 24, 2026

No findings