Ssh Deploy Skill

Universal SSH remote deployment tool - multi-server management, batch deployment, installation script templates with domestic mirror optimization. Supports r...

Security Scan

The skill is an internally consistent SSH deployment tool (paramiko-based) whose requirements and behavior match its description, but it has a few noteworthy security defaults and a small metadata inconsistency you should review before use.

Purpose & Capability

Name/description (SSH remote deployment, templates, batch ops) aligns with the included Python scripts, templates, and required binaries (python3, ssh, scp). The code and templates provide the expected features (inventory, reading ~/.ssh/config, remote exec, SFTP uploads/downloads, mirror setup).

Instruction Scope

The SKILL.md and scripts instruct the agent to read ~/.ssh/config and to save/load inventory from ~/.ssh-deploy/inventory.json. That is expected for an SSH deployer, but it means the skill will enumerate host entries and may reference private key file paths from your SSH config. The tool also supports password fields in inventory.json (with warnings) and pipes arbitrary templates to remote bash; both are functional for deployment but increase risk if misused.

Install Mechanism

No remote download/extract operations are present; the declared install step is a simple pip install paramiko which is proportionate. There is a metadata inconsistency: registry summary said 'No install spec / instruction-only', but SKILL.md includes an install entry for paramiko and the package includes multiple code files — the skill is not purely instruction-only.

Credentials

The skill requests no global credentials, which is appropriate. However it will read SSH configuration (including IdentityFile paths) and can (by design) store passwords in inventory.json (the code shows warnings but still supports plaintext passwords). Templates expect user-provided env vars for things like MYSQL_ROOT_PASSWORD; users must ensure secrets are handled safely. Overall requested env access is minimal, but local config and password storage are areas to be careful with.

Persistence & Privilege

The skill writes configuration/inventory under ~/.ssh-deploy (expected for such a tool) and reads ~/.ssh/config and known_hosts. It does NOT request 'always: true'. A notable default is non-strict host-key handling: the deployer uses paramiko.AutoAddPolicy() by default (auto-accept host keys) and only enables strict host key checking when the user passes --strict. This default favors convenience over security and should be changed for production.

Assessment

This skill appears to be what it says: a paramiko-based SSH deployment tool with templates. Before installing or running it: 1) Review the scripts (deploy.py, inventory.py, templates) and templates to ensure they won't run unexpected commands on your hosts. 2) Be aware it will read your ~/.ssh/config and may reference IdentityFile paths — only allow it if you trust the skill and the environment. 3) Do NOT store plaintext passwords in ~/.ssh-deploy/inventory.json; use SSH keys or an external vault. 4) For production, enable strict host key verification (use the --strict flag) because the default auto-accept behavior is insecure. 5) Note the metadata mismatch: the registry summary made it look instruction-only, but code files exist and SKILL.md instructs installing paramiko — treat it as code you should review. 6) Test on non-production/ephemeral servers first and inspect what templates (e.g., base_setup.sh, install_*.sh) will change before running them across many hosts.

A universal SSH remote deployment tool for managing Linux servers with batch operations, file transfers, and templated software installations. Optimized for domestic network environments with built-in mirror configuration for Chinese mirrors (Aliyun, Tsinghua, etc.).

Quick Start

1. Initial Setup

cd /root/.openclaw/workspace/skills/ssh-deploy-skill

# Auto setup (checks dependencies, creates config)
bash scripts/setup.sh

# Manual dependency install if auto fails
pip3 install --user paramiko

2. Configure Servers (Two Methods)

Method A: Use inventory.json (Traditional)

Edit ~/.ssh-deploy/inventory.json or add servers via CLI:

python3 scripts/inventory.py add web-01 \
  --host 192.168.1.101 \
  --user root \
  --ssh-key ~/.ssh/id_rsa \
  --groups production,web \
  --tags "aliyun"

Config location: All server configurations are saved in ~/.ssh-deploy/inventory.json.

Method B: Read Directly from ~/.ssh/config (New!)

If you already have Host entries in ~/.ssh/config, use them without any additional configuration:

# ~/.ssh/config example
Host dy-c1
    HostName 101.126.92.30
    User root
    IdentityFile ~/.ssh/mypc_id_rsa
    Port 22

# Execute directly using host name
python3 scripts/deploy.py exec dy-c1 "ls -la /opt"

The tool automatically parses Host, HostName, Port, User, IdentityFile fields from your SSH config.

Note: Servers loaded from SSH config are read-only and not saved to inventory. To add groups/tags, import them: inventory.py add --from-ssh-config.

3. Execute Remote Commands

# Single server
python3 scripts/deploy.py exec web-01 "uptime && df -h"

# Batch by group
python3 scripts/deploy.py exec group:production "docker ps"

# Batch by tag
python3 scripts/deploy.py exec tag:aliyun "systemctl status nginx"

# Sequential execution (avoid high load)
python3 scripts/deploy.py exec group:large "apt update" --sequential

4. File Transfers

# Upload file
python3 scripts/deploy.py upload web-01 ./nginx.conf /etc/nginx/nginx.conf

# Batch upload to all group servers
python3 scripts/deploy.py upload group:web ./config.json /opt/app/config.json

# Download file
python3 scripts/deploy.py download web-01 /var/log/nginx/access.log ./logs/

5. Use Templates for Software Installation

All templates in templates/ come pre-configured with domestic mirrors.

# Install Docker (auto-configured with China mirrors)
cat templates/install_docker.sh | python3 scripts/deploy.py exec tag:docker "bash -s"

# Install MySQL (password via environment variable)
MYSQL_ROOT_PASSWORD=YourPass123 cat templates/install_mysql.sh | \
  python3 scripts/deploy.py exec db-01 "bash -s"

# Base setup (system updates + mirrors)
cat templates/base_setup.sh | python3 scripts/deploy.py exec group:all "bash -s"

📦 Installation Script Templates

Template	Software	China Mirror	Env Vars
base_setup.sh	Base environment	✅	-
install_git.sh	Git	❌	GIT_USER_NAME, GIT_USER_EMAIL
install_docker.sh	Docker CE +加速器	✅	-
install_mysql.sh	MySQL 8.0	✅	MYSQL_ROOT_PASSWORD
install_postgresql.sh	PostgreSQL 15	✅	PG_VERSION
install_nginx.sh	Nginx	❌	-
install_nodejs.sh	Node.js	✅ (npm)	NODE_VERSION
install_redis.sh	Redis	❌	-
install_python.sh	Python	✅ (pip)	PYTHON_VERSION

Note: All added server configs are saved to ~/.ssh-deploy/inventory.json.

🎯 Core Features

Server Inventory Management (inventory.py)

# List all servers
python3 scripts/inventory.py list

# Filter by group
python3 scripts/inventory.py list --group production

# Filter by tag
python3 scripts/inventory.py list --tag aliyun

# Add server
python3 scripts/inventory.py add SERVER_NAME \
  --host IP_OR_HOSTNAME \
  --port 22 \
  --user USERNAME \
  --ssh-key PATH_TO_KEY \
  --groups GROUP1,GROUP2 \
  --tags TAG1,TAG2 \
  --desc "description"

Target Syntax (used in deploy.py):

• server-name - Specific server
• group:groupname - All servers in that group
• tag:tagname - All servers with that tag
• * - All servers

Remote Command Execution (deploy.py)

# Parallel batch (default)
python3 scripts/deploy.py exec group:web "docker pull nginx"

# Sequential (large batches or to avoid overload)
python3 scripts/deploy.py exec group:large "apt upgrade -y" --sequential

# Use environment variables
export MYSQL_VERSION="8.0"
cat templates/install_mysql.sh | python3 scripts/deploy.py exec db-01 "bash -s"

File Operations

# Upload (single)
python3 scripts/deploy.py upload web-01 ./local.conf /etc/app/conf.d/conf.conf

# Batch upload
python3 scripts/deploy.py upload group:web ./nginx.conf /etc/nginx/nginx.conf

# Download
python3 scripts/deploy.py download web-01 /var/log/app.log ./logs/

🌏 Domestic Network Optimization

Mirror Configuration

This skill uses Aliyun mirrors by default and configures:

• Ubuntu/Debian → mirrors.aliyun.com
• CentOS/RHEL → mirrors.aliyun.com
• npm → registry.npmmirror.com (Taobao)
• pip → mirrors.aliyun.com/pypi/simple
• Docker → USTC, NetEase, Baidu mirrors
• Go → goproxy.cn
• Maven → Aliyun repository

Detailed config: references/mirrors.md

One-Click Mirror Setup

# Configure system mirrors on all servers
cat templates/base_setup.sh | python3 scripts/deploy.py exec group:all "bash -s"

# Manual Docker mirror config (if needed)
cat <<'EOF' | python3 scripts/deploy.py exec group:all "bash -s"
cat > /etc/docker/daemon.json <<DOCKER
{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com",
    "https://mirror.baidubce.com"
  ]
}
DOCKER
systemctl restart docker
EOF

🔒 Security Best Practices

1. SSH Key Management

   • Use key auth, disable passwords
   • Key permissions: chmod 600 ~/.ssh/id_rsa
   • Different keys for different environments

2. Least Privilege

   • Create dedicated deploy users (not root)
   • Configure passwordless sudo (only necessary commands)
   • Server sshd_config: PermitRootLogin no, PasswordAuthentication no

3. Sensitive Data

   • Never store passwords in inventory.json
   • Use environment variables for passwords (e.g., MYSQL_ROOT_PASSWORD)
   • Config file permissions 640, owner root:appgroup

4. Audit

   • Keep all deployment logs
   • Record command, server, time, result

Full security guide: references/best-practices.md

🐛 Troubleshooting

Quick Diagnostics

# 1. Network test
ping <host>
telnet <host> 22

# 2. Manual SSH test
ssh -i ~/.ssh/id_rsa root@<host> "uptime"

# 3. View connection details
python3 scripts/deploy.py exec <server> "uptime" 2>&1

# 4. Verify key permissions
ls -la ~/.ssh/id_rsa*

Common Issues

Symptom	Solution
Connection refused/timeout	Check server status, SSH service, firewall/security group
Permission denied (publickey)	Check public key in server's ~/.ssh/authorized_keys, key perms 600
sudo: a password is required	Configure passwordless sudo or use root user
Command not found	Use absolute path or ensure PATH includes command
Slow downloads in China	Run base_setup.sh to configure mirrors, see docs/mirrors.md

Detailed troubleshooting: references/troubleshooting.md

📊 Batch Operations Examples

Scenario 1: New Server Initialization

# 1. Add server to inventory
python3 scripts/inventory.py add web-01 --host 1.2.3.101 --groups web --tags production

# 2. Base setup (mirrors, tools)
cat templates/base_setup.sh | python3 scripts/deploy.py exec web-01 "bash -s"

# 3. Install core software
cat templates/install_docker.sh | python3 scripts/deploy.py exec web-01 "bash -s"
cat templates/install_nginx.sh | python3 scripts/deploy.py exec web-01 "bash -s"

# 4. Upload app config
python3 scripts/deploy.py upload web-01 ./app-config.json /opt/app/config.json

# 5. Start application
python3 scripts/deploy.py exec web-01 "docker-compose up -d"

Scenario 2: Rolling Updates Across Multiple Servers

# Canary release: update first batch
cat deploy-v2.sh | python3 scripts/deploy.py exec tag:"canary" "bash -s"

# Check monitoring metrics...

# Full rollout
cat deploy-v2.sh | python3 scripts/deploy.py exec tag:production "bash -s"

Scenario 3: Configuration Sync

# Sync config file to all Web servers
python3 scripts/deploy.py upload group:web ./nginx.conf /etc/nginx/nginx.conf

# Batch restart
python3 scripts/deploy.py exec group:web "nginx -t && systemctl reload nginx"

Scenario 4: Health Checks & Monitoring

# Collect status from all servers
python3 scripts/deploy.py exec "*" "uptime" > uptime-$(date +%F).log

python3 scripts/deploy.py exec "*" "df -h" > disk-$(date +%F).log

python3 scripts/deploy.py exec "*" "docker ps --format 'table {{.Names}}\t{{.Status}}'" > containers-$(date +%F).log

🔄 CI/CD Integration

GitLab CI Example

stages:
  - deploy

deploy_production:
  stage: deploy
  script:
    - pip3 install --user paramiko
    - export TARGET="group:production"
    - cat deploy.sh | python3 skills/ssh-deploy-skill/scripts/deploy.py exec "$TARGET" "bash -s"
  only:
    - main

GitHub Actions Example

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install paramiko
        run: pip3 install paramiko
      - name: Deploy to servers
        run: |
          cat deploy.sh | python3 skills/ssh-deploy-skill/scripts/deploy.py exec "group:staging" "bash -s"

🛠️ Developer Guide

Adding New Installation Templates

1. Create .sh file in templates/
2. Use #!/bin/bash and set -e
3. Detect OS type and adapt (see existing templates)
4. Use env vars for parameters, never hardcode secrets
5. Add domestic mirror config where applicable

Custom Script Structure

#!/bin/bash
set -e

echo "===== Installing XXX ====="

# 1. Detect OS
if [ -f /etc/debian_version ]; then
    OS="debian"
elif [ -f /etc/redhat-release ]; then
    OS="redhat"
else
    echo "Unsupported OS"
    exit 1
fi

# 2. Configure domestic mirrors (if needed)
# ...

# 3. Install software
if [ "$OS" = "debian" ]; then
    apt-get update
    apt-get install -y xxx
elif [ "$OS" = "redhat" ]; then
    yum install -y xxx
fi

# 4. Start service
systemctl start xxx
systemctl enable xxx

echo "XXX installation complete!"

Using Python API Directly

from inventory import Inventory, Server
from deploy import SSHDeployer

# Load inventory
inv = Inventory()
server = inv.get_server("web-01")

# Create deployer
deployer = SSHDeployer()

# Execute command
result = deployer.execute(server, "docker ps")
print(result.success, result.output)

# Upload file
res = deployer.upload_file(server, "./local.conf", "/etc/conf.d/local.conf")

deployer.close()

📚 Additional Documentation

Detailed documentation (some in Chinese):

• README.md - Complete usage guide with API reference
• README.zh-CN.md - Full Chinese manual
• references/mirrors.md - Domestic mirror configuration details
• references/best-practices.md - Best practices and code examples
• references/troubleshooting.md - Complete troubleshooting handbook

🤝 Contributing

Issues and Pull Requests are welcome!

📄 License

MIT License