.\" Manpage for bssh
.\" Contact the maintainers to correct errors or typos.
.TH BSSH 1 "August 2025" "v0.7.0" "bssh Manual"
.SH NAME
bssh \- Broadcast SSH - SSH-compatible client with parallel execution capabilities
.SH SYNOPSIS
.B bssh
[\fIOPTIONS\fR] [\fIdestination\fR] [\fIcommand\fR [\fIargument\fR...]]
.br
.B bssh
[\fIOPTIONS\fR] \fICOMMAND\fR
.SH DESCRIPTION
.B bssh
is a high-performance SSH client that can be used as a drop-in replacement for standard SSH while also providing
powerful parallel execution capabilities for cluster management. Built with Rust, it supports both single-host
SSH connections (SSH compatibility mode) and multi-server operations (cluster mode).
.B SSH Compatibility Mode:
When used with a single destination (e.g., bssh user@host), bssh behaves like standard SSH, supporting
common SSH options and automatically starting an interactive shell when no command is provided.
.B Multi-Server Mode:
When used with clusters (-C) or multiple hosts (-H), bssh executes commands across multiple nodes
simultaneously with real-time output streaming.
The tool provides secure file transfer capabilities using SFTP protocol, supports multiple authentication
methods (SSH keys with passphrase support, SSH agent, password), and automatically detects Backend.AI
multi-node session environments.
.SH OPTIONS
.SS SSH-Compatible Options
.TP
.BR \-i " " \fIidentity_file\fR
SSH private key file path (same as ssh -i)
.TP
.BR \-l " " \fIlogin_name\fR
Specifies the user to log in as on the remote machine (same as ssh -l)
.TP
.BR \-p " " \fIport\fR
Port to connect to on the remote host (same as ssh -p)
.TP
.BR \-o " " \fIoption\fR
SSH options in key=value format (e.g., -o StrictHostKeyChecking=no)
Can be specified multiple times
.TP
.BR \-F " " \fIconfigfile\fR
Specifies an alternative SSH configuration file
.TP
.BR \-q
Quiet mode (suppress non-error messages)
.TP
.BR \-t
Force pseudo-terminal allocation
.TP
.BR \-T
Disable pseudo-terminal allocation
.TP
.BR \-J " " \fIdestination\fR
Connect via jump host(s) (ProxyJump) [planned feature]
.TP
.BR \-Q " " \fIquery_option\fR
Query SSH configuration options (cipher, kex, mac, key, protocol-version, help)
.TP
.BR \-4
Force use of IPv4 addresses only
.TP
.BR \-6
Force use of IPv6 addresses only
.TP
.BR \-x
Disable X11 forwarding
.SS Multi-Server Options
.TP
.BR \-H ", " \-\-hosts " " \fIHOSTS\fR
Comma-separated list of hosts in [user@]hostname[:port] format.
Example: user1@host1:2222,user2@host2
.TP
.BR \-C ", " \-\-cluster " " \fICLUSTER\fR
Cluster name from configuration file (uppercase C for multi-server mode)
.TP
.BR \-\-config " " \fICONFIG\fR
Configuration file path (default: ~/.config/bssh/config.yaml)
.TP
.BR \-A ", " \-\-use\-agent
Use SSH agent for authentication (Unix/Linux/macOS only).
When this option is specified, bssh will attempt to use the SSH agent
for authentication. Falls back to key file authentication if the agent
is not available or authentication fails.
.TP
.BR \-\-password
Use password authentication. When this option is specified, bssh will
prompt for the password securely without echoing it to the terminal.
This is useful for systems that don't have SSH keys configured.
.TP
.BR \-\-parallel " " \fIPARALLEL\fR
Maximum parallel connections for multi-server mode (default: 10)
Note: -p is now used for port (SSH compatibility)
.TP
.BR \-\-output\-dir " " \fIOUTPUT_DIR\fR
Output directory for command results. When specified, saves command outputs
to separate files for each node with stdout, stderr, and execution summary
.TP
.BR \-v ", " \-\-verbose
Increase verbosity (can be used multiple times: -v, -vv, -vvv)
.TP
.BR \-\-strict\-host\-key\-checking " " \fIMODE\fR
Host key checking mode: yes, no, or accept-new (default: accept-new)
.TP
.BR \-h ", " \-\-help
Print help information
.TP
.BR \-V ", " \-\-version
Print version information
.SH COMMANDS
.TP
.B exec
Execute a command on specified hosts
.TP
.B list
List available clusters from configuration
.TP
.B ping
Test connectivity to hosts
.TP
.B upload
Upload files to remote hosts using SFTP (supports glob patterns)
.RS
Usage: bssh upload \fISOURCE\fR \fIDESTINATION\fR
.br
Uploads the local file(s) matching SOURCE pattern to DESTINATION path on all specified remote hosts.
SOURCE can be a single file path or a glob pattern (e.g., *.txt, logs/*.log).
When uploading multiple files, DESTINATION should be a directory (end with /).
Uses SFTP protocol for secure file transfer with progress indicators.
.RE
.TP
.B download
Download files from remote hosts using SFTP (supports glob patterns)
.RS
Usage: bssh download \fISOURCE\fR \fIDESTINATION\fR
.br
Downloads the remote file(s) matching SOURCE pattern from all specified hosts to the local DESTINATION directory.
SOURCE can be a single file path or a glob pattern (e.g., /var/log/*.log, /etc/*.conf).
Each downloaded file is saved with a unique name prefixed by the hostname.
Uses SFTP protocol for secure file transfer with progress indicators.
.RE
.TP
.B interactive
Start an interactive shell session on cluster nodes
.RS
Usage: bssh interactive [\fIOPTIONS\fR]
.br
Opens an interactive shell session with one or more remote hosts. Supports both single-node
and multiplex modes. In multiplex mode, commands are sent to all active nodes simultaneously.
.PP
Options:
.IP "\-\-single\-node"
Connect to a single node instead of multiplexing to all nodes
.IP "\-\-multiplex"
Multiplex input across all nodes (default behavior)
.IP "\-\-prompt\-format FORMAT"
Custom prompt format with variables: {node}, {user}, {host}, {pwd}
.IP "\-\-history\-file PATH"
History file path for command history (default: ~/.bssh_history)
.IP "\-\-work\-dir DIR"
Initial working directory on remote hosts
.PP
Interactive mode settings can be configured globally or per-cluster in the configuration file.
CLI arguments override configuration file settings.
.RE
.SH CONFIGURATION
.B bssh
loads configuration from the following sources in priority order:
.IP 1. 4
Backend.AI environment variables (automatic detection)
.IP 2. 4
Current directory (./config.yaml)
.IP 3. 4
XDG config directory ($XDG_CONFIG_HOME/bssh/config.yaml or ~/.config/bssh/config.yaml)
.IP 4. 4
CLI specified path (via --config flag)
.SS Configuration File Format
.nf
defaults:
user: admin
port: 22
ssh_key: ~/.ssh/id_rsa
parallel: 10
# Global interactive mode settings (optional)
interactive:
default_mode: multiplex # single_node or multiplex
prompt_format: "[{node}] $ " # Variables: {node}, {user}, {host}, {pwd}
history_file: ~/.bssh_history
show_timestamps: false # Show timestamps in output
work_dir: /home/admin # Initial working directory
broadcast_prefix: "!all " # Prefix for broadcasting to all nodes
node_switch_prefix: "!" # Prefix for special commands
clusters:
production:
nodes:
- web1.example.com
- web2.example.com
- user@web3.example.com:2222
ssh_key: ~/.ssh/prod_key
# Cluster-specific interactive settings (overrides global)
interactive:
default_mode: single_node
prompt_format: "prod> "
work_dir: /var/www
staging:
nodes:
- host: staging1.example.com
port: 2200
user: deploy
- staging2.example.com
user: staging_user
.fi
.SH BACKEND.AI INTEGRATION
When running inside a Backend.AI multi-node session, bssh automatically detects cluster configuration
from environment variables:
.TP
.B BACKENDAI_CLUSTER_HOSTS
Comma-separated list of all node hostnames
.TP
.B BACKENDAI_CLUSTER_HOST
Current node's hostname
.TP
.B BACKENDAI_CLUSTER_ROLE
Current node's role (main or sub)
Note: Backend.AI multi-node clusters use SSH port 2200 by default, which is automatically configured.
.SH EXAMPLES
.SS SSH Compatibility Mode (Single Host)
.TP
Connect to a host (interactive shell):
.B bssh user@hostname
.TP
Execute a command:
.B bssh user@hostname "uptime"
.TP
Specify port and key:
.B bssh -p 2222 -i ~/.ssh/key.pem admin@server.com
.TP
Use SSH options:
.B bssh -o StrictHostKeyChecking=no user@host
.TP
Query SSH capabilities:
.B bssh -Q cipher
.SS Multi-Server Mode
.TP
Execute command on multiple hosts:
.B bssh -H "user1@host1,user2@host2" "uptime"
.TP
Use cluster from configuration:
.B bssh -C production "df -h"
.TP
Test connectivity:
.B bssh -C production ping
.TP
Upload file to remote hosts (SFTP):
.B bssh -C production upload local_file.txt /tmp/remote_file.txt
.TP
Download file from remote hosts (SFTP):
.B bssh -C production download /etc/passwd ./downloads/
.RS
Downloads /etc/passwd from each host to ./downloads/ directory.
Files are saved as hostname_passwd (e.g., web1_passwd, web2_passwd)
.RE
.TP
Backend.AI multi-node session (automatic):
.B bssh "nvidia-smi"
.TP
Increase verbosity for debugging:
.B bssh -vv -H localhost "echo test"
.TP
Use custom SSH key:
.B bssh -i ~/.ssh/custom_key -C staging "systemctl status"
.TP
Use SSH agent for authentication:
.B bssh -A -C production "systemctl status"
.TP
Use password authentication:
.B bssh -P -H "user@host.com" "uptime"
.RS
Prompts for password interactively
.RE
.TP
Use encrypted SSH key:
.B bssh -i ~/.ssh/encrypted_key -C production "df -h"
.RS
Automatically detects encrypted key and prompts for passphrase
.RE
.TP
Save output to files:
.B bssh --output-dir ./results -C production "ps aux"
.RS
Creates timestamped files per node:
.br
- hostname_TIMESTAMP.stdout (standard output)
.br
- hostname_TIMESTAMP.stderr (error output)
.br
- hostname_TIMESTAMP.error (connection errors)
.br
- summary_TIMESTAMP.txt (execution summary)
.RE
.TP
Upload configuration file to all nodes:
.B bssh -H "node1,node2,node3" upload /etc/myapp.conf /etc/myapp.conf
.TP
Download logs from all web servers:
.B bssh -C webservers download /var/log/nginx/access.log ./logs/
.RS
Each file is saved as hostname_access.log in the ./logs/ directory
.RE
.TP
Upload with custom SSH key and increased parallelism:
.B bssh -i ~/.ssh/deploy_key --parallel 20 -C production upload deploy.tar.gz /tmp/
.TP
Upload multiple files with glob pattern:
.B bssh -C production upload "*.log" /var/backups/logs/
.RS
Uploads all .log files from current directory to /var/backups/logs/ on all nodes
.RE
.TP
Download logs with wildcard pattern:
.B bssh -C production download "/var/log/app*.log" ./collected_logs/
.RS
Downloads all files matching app*.log from /var/log/ on each node
.RE
.TP
Start interactive mode with all nodes:
.B bssh -C production interactive
.RS
Opens an interactive shell session with all nodes in multiplex mode
.RE
.TP
Start interactive mode with single node:
.B bssh -C production interactive --single-node
.RS
Prompts to select one node for interactive session
.RE
.TP
Interactive mode with custom prompt:
.B bssh -H server1,server2 interactive --prompt-format "{user}@{host}> "
.TP
Interactive mode with initial working directory:
.B bssh -C staging interactive --work-dir /var/www
.RS
Sets initial working directory to /var/www on all nodes
.RE
.SS Interactive Mode Special Commands
When in interactive mode, the following special commands are available (default prefix is !):
.IP "!all"
Activate all connected nodes
.IP "!broadcast <cmd>"
Execute command on all nodes temporarily
.IP "!node<N>"
Switch to node N (e.g., !node1, !node2)
.IP "!list"
List all nodes with their connection status
.IP "!status"
Show currently active nodes
.IP "!help"
Show help for special commands
.IP "exit"
Exit interactive mode
.PP
Note: The special command prefix can be customized in the configuration file.
.SH EXIT STATUS
.TP
.B 0
Success - all commands executed successfully on all nodes
.TP
.B 1
Failure - one or more commands failed or connection errors occurred
.SH OUTPUT FILES
When using the
.B --output-dir
option, bssh creates the following files:
.TP
.I hostname_YYYYMMDD_HHMMSS.stdout
Standard output from successful command execution
.TP
.I hostname_YYYYMMDD_HHMMSS.stderr
Standard error output (created only if stderr is not empty)
.TP
.I hostname_YYYYMMDD_HHMMSS.error
Error messages for failed connections or command execution
.TP
.I hostname_YYYYMMDD_HHMMSS.empty
Marker file when command produces no output
.TP
.I summary_YYYYMMDD_HHMMSS.txt
Overall execution summary with success/failure counts for all nodes
Each output file includes metadata headers with command, host, user, exit status, and timestamp information.
.SH FILES
.TP
.I ~/.config/bssh/config.yaml
Default configuration file (XDG Base Directory standard)
.TP
.I $XDG_CONFIG_HOME/bssh/config.yaml
Configuration file when XDG_CONFIG_HOME is set
.TP
.I ~/.ssh/known_hosts
SSH known hosts file for host key verification
.TP
.I ~/.ssh/id_ed25519, ~/.ssh/id_rsa, ~/.ssh/id_ecdsa, ~/.ssh/id_dsa
Default SSH private keys (checked in order of preference). If a key is
encrypted, bssh will prompt for the passphrase.
.TP
.I $SSH_AUTH_SOCK
SSH agent socket for agent-based authentication
.SH ENVIRONMENT
.TP
.B USER
Used as default username when not specified
.TP
.B HOME
Used for expanding tilde (~) in paths
.TP
.B BACKENDAI_CLUSTER_HOSTS
Backend.AI cluster node list
.TP
.B BACKENDAI_CLUSTER_HOST
Backend.AI current node hostname
.TP
.B BACKENDAI_CLUSTER_ROLE
Backend.AI node role (main/sub)
.TP
.B SSH_AUTH_SOCK
SSH agent socket path. When set, bssh can automatically detect and use
the SSH agent for authentication without specifying the -A flag
.SH AUTHOR
Written by Jeongkyu Shin and the Lablup team.
.br
Developed and maintained as part of the Backend.AI project.
.SH REPORTING BUGS
Report bugs to: https://github.com/lablup/bssh/issues
.SH COPYRIGHT
Copyright � 2025 Lablup Inc. and Jeongkyu Shin
.br
Licensed under the Apache License, Version 2.0
.SH SEE ALSO
.BR ssh (1),
.BR scp (1),
.BR sftp (1),
.BR ssh-agent (1),
.BR ssh-keygen (1)
.SH NOTES
.SS Breaking Changes (v0.5.3+)
.TP
.B Cluster option changed:
The cluster option has changed from lowercase -c to uppercase -C to avoid conflicts
with SSH's -c (cipher) option. Update your scripts accordingly.
.TP
.B Parallel option changed:
The -p option now specifies port (SSH compatibility). For parallel connections,
use --parallel instead.
.SS SFTP Requirements
The upload and download commands require SFTP subsystem to be enabled on the remote SSH servers.
Most SSH servers have SFTP enabled by default with a configuration line like:
.br
.I Subsystem sftp /usr/lib/openssh/sftp-server
.br
or
.br
.I Subsystem sftp internal-sftp
.SS Performance
File transfers use SFTP protocol which provides secure and reliable transfers.
The parallel transfer capability allows simultaneous uploads/downloads to multiple nodes,
significantly reducing total transfer time for cluster-wide file distribution or collection.
For more information and documentation, visit:
.br
https://github.com/lablup/bssh