.\" Manpage for bssh
.\" Contact the maintainers to correct errors or typos.
.TH BSSH 1 "August 22, 2025" "v0.5.0" "bssh Manual"
.SH NAME
bssh \- Backend.AI SSH - Parallel command execution across cluster nodes
.SH SYNOPSIS
.B bssh
[\fIOPTIONS\fR] [\fICOMMAND_ARGS\fR...] [\fICOMMAND\fR]
.SH DESCRIPTION
.B bssh
is a high-performance parallel SSH command execution tool for cluster management, built with Rust.
It enables efficient execution of commands across multiple nodes simultaneously with real-time output streaming.
The tool provides secure file transfer capabilities using SFTP protocol for both uploading and downloading files
to/from multiple remote hosts in parallel. It supports multiple authentication methods including SSH keys (with
passphrase support for encrypted keys), SSH agent, and password authentication. It automatically detects Backend.AI
multi-node session environments and supports various configuration methods.
.SH 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
.TP
.BR \-\-config " " \fICONFIG\fR
Configuration file path (default: ~/.config/bssh/config.yaml)
.TP
.BR \-u ", " \-\-user " " \fIUSER\fR
Default username for SSH connections
.TP
.BR \-i ", " \-\-identity " " \fIIDENTITY\fR
SSH private key file path. If the key is encrypted, bssh will
automatically prompt for the passphrase.
.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 \-P ", " \-\-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 \-p ", " \-\-parallel " " \fIPARALLEL\fR
Maximum parallel connections (default: 10)
.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
.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
clusters:
production:
nodes:
- web1.example.com
- web2.example.com
- user@web3.example.com:2222
ssh_key: ~/.ssh/prod_key
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
.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 -p 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
.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 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