SSH Commander

SSH Commander is a powerful, colorful command-line tool for executing commands across multiple SSH servers simultaneously. It supports both password and key-based authentication, custom ports, and can execute both single commands and command files.

Features

• 🔑 Supports both password and key-based authentication
• 🌈 Colorized output for better readability
• 📁 Execute commands from files
• 🔄 Interactive server management
• 🔒 Secure password handling (never shown in terminal)
• 🚀 Single binary deployment
• ⚙️ YAML-based configuration
• 📊 Real-time output streaming
• ⌨️ Graceful interrupt handling (Ctrl+C support)

System Requirements

Linux

Ubuntu/Debian:

• Modern systems: libffi8 and libssl3
• Older systems: libffi7 and libssl1.1

CentOS/RHEL:

• Modern systems: libffi-8 and openssl-3
• Older systems: libffi-7 and openssl-1.1

Windows

• Microsoft Visual C++ Redistributable

macOS

• No additional requirements

Installation

Option 1: Debian Package (Ubuntu/Debian)

1. Download the latest .deb package from the releases page
2. Install using dpkg:

sudo dpkg -i ssh-commander_*.deb

If you encounter any dependency errors during installation, run:

sudo apt -f install

This will automatically install any missing dependencies and complete the installation.

Option 2: Using Pre-built Binaries

1. Download the latest release for your platform from the releases page
2. Extract the archive
3. Run the installation script:

./install.sh  # For macOS/Linux
.\install.ps1  # For Windows (Run as Administrator)

Option 3: Building from Source

1. Clone the repository:

git clone https://github.com/AthenaNetworks/ssh_commander.git
cd ssh_commander

2. Create a virtual environment and install dependencies:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

3. Build the executable:

./build_all.sh

Configuration

SSH Commander stores server configurations in ~/.config/ssh-commander/servers.yaml. This file is automatically created when you add your first server.

Configuration Format

The configuration file uses YAML format and supports both key-based and password authentication:

# Key-based authentication (recommended)
- hostname: web1.example.com
  username: admin
  key_file: ~/.ssh/id_rsa  # Path to your SSH key
  port: 22  # Optional, defaults to 22
  tags: [prod, web]  # Optional, defaults to ['default']

# Password authentication
- hostname: db1.example.com
  username: dbadmin
  password: your_secure_password  # Not recommended for production use
  port: 2222
  tags: [prod, db]  # Optional server tags

Security Notes

⚠️ Important Security Warning:

• Passwords are stored in plaintext and are NOT secure
• Anyone with access to your config file can see the passwords
• This includes backup systems, cloud sync, etc.

✅ Recommended Approach:

• Use key-based authentication instead
  • Generate an SSH key: ssh-keygen -t ed25519
  • Copy to server: ssh-copy-id user@hostname
  • Use key_file: ~/.ssh/id_ed25519 in config

Configuration Security

• Config file is searched for in the following order:
  1. Path specified by --config argument
  2. servers.yaml in the same directory as the executable
  3. ~/.config/ssh-commander/servers.yaml
• File permissions are set to user-only read/write (600)
• SSH key paths support ~ expansion to your home directory

Usage

Managing Servers

1. Add a new server interactively:

ssh-commander add

2. Add a server non-interactively (great for scripts/automation):

ssh-commander add -y \
    --hostname web1.example.com \
    --username admin \
    --key-file ~/.ssh/id_ed25519 \
    --tags prod,web

3. Edit an existing server in place:

ssh-commander edit web1.example.com --port 2222 --tags prod,web,frontend
ssh-commander edit web1.example.com --rename web1-new.example.com
ssh-commander edit db1.example.com --key-file ~/.ssh/id_ed25519

4. List configured servers (with optional filter and machine-readable output):

ssh-commander list                       # pretty
ssh-commander list -t prod -o hosts      # one hostname per line
ssh-commander list -o json               # JSON dump for jq/scripting

5. Remove one or more servers (prompts for confirmation):

ssh-commander remove web1.example.com web2.example.com
ssh-commander remove old-host.example.com --yes  # no prompt

6. Test SSH connectivity to all (or a subset of) servers:

ssh-commander test
ssh-commander test -t prod --parallel 8

7. Show the resolved config file path:

ssh-commander config-path

Executing Commands

1. Run a single command on all servers:

ssh-commander exec -c "uptime"

2. Run a command on servers with specific tags:

ssh-commander exec -c "uptime" -t prod,web

3. Run a command across many servers in parallel:

ssh-commander exec -c "uptime" --parallel 8

4. Run multiple commands from a file:

ssh-commander exec -f commands.txt

5. Run commands from file on specific tags, stopping on the first failure:

ssh-commander exec -f commands.txt -t staging --stop-on-error

Example commands.txt:

# This is a comment - it will be skipped.
uptime
df -h
free -m
who

6. Use a different config file:

ssh-commander --config prod-servers.yaml exec -c "docker ps"

Global Flags

All commands accept the following global options:

Flag	Description
--config FILE	Override the config file path.
--timeout SECONDS	SSH connect/banner/auth timeout (default 10).
--no-color	Disable ANSI color output (also respects piped output where possible).
-q, --quiet	Suppress informational output (errors still print).
-v, --verbose	Print extra diagnostic detail (incl. tracebacks on failure).
--strict-host-key-checking	Reject unknown SSH host keys instead of auto-adding them.

Exit Codes

Code	Meaning
0	Success.
1	User error (bad flags, missing config, etc.).
2	Invalid CLI argument.
3	One or more servers exited non-zero / failed connectivity.
4	DNS / network error.
130	Interrupted (Ctrl+C).

Real-world Examples

1. Check system status across all servers:

ssh-commander exec -c "systemctl status nginx"

2. Deploy updates:

ssh-commander exec -c "sudo apt update && sudo apt upgrade -y"

3. Monitor disk space:

ssh-commander exec -c "df -h / /var /home"

4. Check running Docker containers:

ssh-commander exec -c "docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'"

5. Execute a maintenance script:

# maintenance.txt
systemctl status nginx
df -h
free -m
find /var/log -type f -size +100M -exec ls -lh {} \;

# Run maintenance checks
ssh-commander exec -f maintenance.txt

Output Formatting

SSH Commander uses colors to make output more readable:

• 🔵 Server names are highlighted in blue
• 🟢 Successful output is shown in green
• 🔴 Errors are displayed in red
• 🟣 Command execution status in purple

Security Considerations

1. Password Storage:

   • Passwords in the config file should be treated with care
   • Consider using key-based authentication when possible
   • Use appropriate file permissions for your config file: chmod 600 servers.yaml

2. SSH Keys:

   • Key files should have proper permissions: chmod 600 ~/.ssh/id_rsa
   • Consider using different keys for different server groups

3. Network Security:

   • Be mindful of firewalls and network policies
   • Use custom ports if needed
   • Consider using jump hosts for isolated networks

Contributing

1. Fork the repository
2. Create your feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0) - see the LICENSE file for details.

Key points of the GPL-3.0 license:

• ✅ You can use this software for commercial purposes
• ✅ You can modify the source code
• ✅ You can distribute your modifications
• ⚠️ You must disclose the source code of your modifications
• ⚠️ You must license your modifications under the GPL-3.0
• ⚠️ You must state the significant changes you made

Support

If you encounter any issues or have questions:

1. Check the Issues page
2. Create a new issue with detailed information about your problem
3. Include your OS version and Python version when reporting bugs