Skip to content

release v3.1

Latest
Latest

Choose a tag to compare

View all tags
@meirm meirm released this 02 Sep 17:17
· 1 commit to main since this release
release
4159011

bssh Python v3.1.0 Release Notes

Released: January 2, 2025

What's New

🗂️ Organized File Downloads with --host-dirs

The new --host-dirs option for bget and bgets commands provides a cleaner way to organize downloaded files from multiple servers:

# Traditional format (default)
bget @webservers -- /var/log/nginx/access.log ./logs/
# Creates: ./logs/access.log-web01, ./logs/access.log-web02

# New organized format
bget --host-dirs @webservers -- /var/log/nginx/access.log ./logs/
# Creates: ./logs/web01/access.log, ./logs/web02/access.log

This makes it easier to:

  • Keep files from different servers organized
  • Compare files across servers
  • Archive logs by server
  • Process files with scripts that expect directory-based organization

🔧 Standardized Command Syntax

All file transfer commands now consistently use the -- separator between node patterns and file arguments:

# Upload to multiple servers
bput @production -- config.json /etc/app/config.json

# Download from specific servers
bget web01: web02: -- /etc/nginx/nginx.conf ./backups/

# Sequential transfers
bputs @staging -- large_file.tar.gz /tmp/
bgets @databases -- /var/backups/db.dump ./backups/

Benefits:

  • Clear separation between node selection and file paths
  • Consistent syntax across all commands
  • No ambiguity with complex patterns
  • Easier to script and automate

📝 Improved Pattern Handling

Node exclusion patterns (-@group) now work without requiring quotes or special escaping:

# Works naturally without quotes
bssh @all -@staging -@development -- df -h

# Complex patterns are handled correctly
bput @webservers -@maintenance -- update.tar.gz /tmp/

⏱️ Explicit Timeout Support

Timeout configuration is now fully documented and available for all commands:

# Quick commands with short timeout
bssh --timeout 5 @monitoring -- ping -c 1 google.com

# Long-running transfers with extended timeout
bput --timeout 300 @backup -- large_backup.tar.gz /mnt/backups/

Breaking Changes

File Transfer Command Syntax

File transfer commands now require the -- separator:

Before (v3.0):

bput local.txt /remote/path @servers
bget /remote/file local/ @servers

After (v3.1):

bput @servers -- local.txt /remote/path
bget @servers -- /remote/file local/

Migration: Update scripts to place node patterns before -- and file arguments after.

Bug Fixes

  • Pattern Parsing: Fixed -@group exclusion patterns that previously required quoting
  • Path Construction: Corrected --host-dirs to create proper destination/hostname/filename structure
  • Error Messages: Improved clarity when -- separator is missing
  • Consistency: All commands now use the same argument parsing logic

Upgrading

From v3.0.0

# Upgrade the package
pip install --upgrade bssh

# Update scripts to use new syntax
# Old: bput file.txt /remote/ @servers
# New: bput @servers -- file.txt /remote/

From v2.0.0

First upgrade to v3.0.0 and migrate your nodes file, then upgrade to v3.1.0:

# Convert nodes file to v3 format
python convert_nodes_v3.py ~/.bssh/nodes -o ~/.bssh/nodes.v3
mv ~/.bssh/nodes ~/.bssh/nodes.old
mv ~/.bssh/nodes.v3 ~/.bssh/nodes

# Upgrade to v3.1.0
pip install --upgrade bssh

Examples

Collecting Logs from Multiple Servers

# Collect nginx logs with organized structure
bget --host-dirs @webservers -- /var/log/nginx/access.log ./logs/nginx/

# Result:
# ./logs/nginx/web01/access.log
# ./logs/nginx/web02/access.log
# ./logs/nginx/web03/access.log

Deploying Configuration Files

# Deploy to production excluding maintenance servers
bput @production -@maintenance -- app.conf /etc/myapp/app.conf

# Verify deployment
bssh @production -@maintenance -- cat /etc/myapp/app.conf | grep -i version

Batch Operations with Timeouts

# Quick health check with 3-second timeout
bssh --timeout 3 @all -- uptime

# Long backup transfer with 10-minute timeout
bget --timeout 600 @databases -- /backup/database.dump ./backups/

Testing Your Setup

Always test with --dry-run before running commands in production:

# Test command execution
bssh --dry-run @production -- systemctl restart nginx

# Test file upload
bput --dry-run @webservers -- config.txt /etc/app/

# Test file download with new option
bget --dry-run --host-dirs @all -- /var/log/app.log ./logs/

Compatibility

  • Python: 3.11 or higher required
  • Nodes File: v3.0 format (semicolon-separated) fully supported
  • SSH: Uses system SSH defaults (~/.ssh/config, ssh-agent)
  • Platforms: Linux, macOS, Unix-like systems

Getting Help

Credits

Python implementation by Meir Michanie (2025)
Based on the original Perl bssh tools (2006)

Assets 3
Loading