Shellmin

A fast, parallel CLI tool for managing Linux servers via SSH with extensible scripting support.

Shellmin provides a unified interface for managing multiple Linux servers simultaneously, with built-in support for common sysadmin tasks and a powerful plugin system for custom automation.

✨ Features

• Parallel Execution: Run commands across multiple servers simultaneously
• SSH Connection Management: Efficient connection pooling and reuse with health monitoring
• Host Management: Add, list, and execute commands on configured hosts
• Extensible Module System: Execute bash scripts organized by OS and action with stdout-based state signaling
• Server Inventory: Manage server configurations and SSH keys
• Security Validation: Built-in command validation and injection prevention
• Performance Monitoring: Real-time operation timing and statistics
• YAML Configuration: Support for YAML configuration files

🚀 Quick Start

Installation

git clone https://gitlab.com/renich/shellmin.git
cd shellmin
shards install
make build
sudo cp bin/shellmin /usr/local/bin/

Basic Usage

1. Add Hosts:

   shellmin host add --name web-server --host 192.168.1.100 --user admin
   shellmin host list
   shellmin host show
   

2. Execute Commands:

shellmin host exec --all "uptime"

3. **Run Modules**:
   ```bash
   shellmin module packages install nginx --all

4. Manage State:

   shellmin state get installed_version
   shellmin state set config_version 2.0
   

shellmin state versions # View version history shellmin state rollback 0 # Rollback to previous version

## 🔧 Advanced Features

### State Versioning

Shellmin automatically tracks state changes with full version history:

```bash
# View state history
shellmin state versions

# Rollback to previous version
shellmin state rollback 0

# State files include version metadata
~/.config/shellmin/state/host.module.json

Performance Monitoring

Track execution times and identify bottlenecks:

shellmin performance report
shellmin performance stats ssh_connect

Configuration Access

Modules can securely read configuration values:

# In scripts
config_value=$(shellmin config get hosts.web-server.user)

Security Features

• Command injection prevention
• Path traversal protection
• Environment variable validation
• Script content scanning for dangerous patterns
• Audit logging for all operations

📚 Module Development

Shellmin modules are pure scripts that leverage environment variables and state management for powerful automation.

Module Structure

modules/
├── packages/
│   ├── generic/
│   │   ├── install.bash
│   │   ├── remove.bash
│   │   └── update.bash
│   ├── ubuntu/
│   │   └── install.bash
│   └── centos/
│       └── install.bash

Environment Variables

Modules receive comprehensive context via environment variables:

• SHELLMIN_HOST_NAME: Target host name
• SHELLMIN_HOST_IP: Target host IP address
• SHELLMIN_MODULE_NAME: Current module name
• SHELLMIN_MODULE_ACTION: Action being performed
• SHELLMIN_OS: Detected OS (ubuntu, centos, fedora, etc.)
• SHELLMIN_STATE_FILE: Path to state file

State Management

Persist data between module runs:

# Set state in stdout
echo "SHELLMIN_STATE_SET: installed_version=1.2.3"
echo "SHELLMIN_STATE_SET: config_updated=true"

# State is automatically saved as JSON

Example Module

#!/bin/bash
# packages/generic/install.bash

set -euo pipefail

PACKAGES="${SHELLMIN_PACKAGES:-}"

if [[ -z "$PACKAGES" ]]; then
    echo "❌ Error: Specify packages with SHELLMIN_PACKAGES=pkg1,pkg2"
    exit 1
fi

echo "📦 Installing packages on $SHELLMIN_HOST_NAME ($SHELLMIN_OS)"

# Detect package manager
case "$SHELLMIN_OS" in
    ubuntu|debian)
        apt update && apt install -y $PACKAGES
        ;;
    centos|rhel|fedora)
        yum install -y $PACKAGES
        ;;
    *)
        echo "❌ Unsupported OS: $SHELLMIN_OS"
        exit 1
        ;;
esac

# Update state
for pkg in $PACKAGES; do
    echo "SHELLMIN_STATE_SET: package_$pkg=installed"
done

echo "✅ Installation completed"

Supported Languages

Modules can be written in multiple languages with automatic detection:

• Bash/Shell: .sh, .bash files or #!/bin/bash shebang
• Python: .py files or #!/usr/bin/env python shebang
• Ruby: .rb files or #!/usr/bin/env ruby shebang
• Perl: .pl files or #!/usr/bin/env perl shebang
• Node.js: .js files or #!/usr/bin/env node shebang
• Lua: .lua files or #!/usr/bin/env lua shebang
• PHP: .php files or #!/usr/bin/env php shebang

Testing Modules

# List available modules
shellmin module list

# Test locally (if enabled)
shellmin packages install nginx

# Test on remote hosts
shellmin packages install nginx --hosts web-server

📚 Documentation

• Usage Guide
• Architecture
• Module System & Paradigms
• API Reference (generated by crystal docs)

🛠️ Development

make dev  # format, lint, test, build
make test # run specs

See ROADMAP.md for planned features.

🤝 Contributing

See CODE_OF_HONOR.rst for guidelines.

📄 License

MIT License - see LICENSE.