Securely connect to and manage remote Linux/Unix servers via SSH. Execute commands, transfer files (SCP/SFTP), set up port forwarding and tunnels. Use when the user asks to SSH into a server, connect to a remote machine, run remote commands, upload/download files to servers, set up tunnels, or perform server administration tasks. Works on Windows, macOS, and Linux.
apm install @fgarofalo56/ssh-server-admin
[](https://apm-p1ls2dz87-atlamors-projects.vercel.app/packages/@fgarofalo56/ssh-server-admin)---
name: ssh-server-admin
description: Securely connect to and manage remote Linux/Unix servers via SSH. Execute commands, transfer files (SCP/SFTP), set up port forwarding and tunnels. Use when the user asks to SSH into a server, connect to a remote machine, run remote commands, upload/download files to servers, set up tunnels, or perform server administration tasks. Works on Windows, macOS, and Linux.
---
# SSH Server Administration
A comprehensive skill for secure remote server management via SSH. Supports command execution, file transfers, port forwarding, and tunneling. **Cross-platform compatible: Windows, macOS, and Linux.**
## Platform Detection
**CRITICAL: Detect the operating system first to use the correct SSH approach.**
Before executing SSH commands, check the platform:
- **Windows**: Use PowerShell or Windows OpenSSH (built into Windows 10+)
- **macOS/Linux**: Use standard bash SSH commands
## Authentication Methods (In Order of Preference)
### 1. SSH Key Authentication (RECOMMENDED - Works Everywhere)
SSH keys are the most secure and reliable method. They work identically on all platforms.
**Check for existing keys:**
```bash
# Windows (PowerShell)
Get-ChildItem ~/.ssh/id_*.pub
# macOS/Linux
ls -la ~/.ssh/id_*.pub
```
**If keys exist, use them:**
```bash
# All platforms - key auth is automatic if keys are set up
ssh -o StrictHostKeyChecking=accept-new [username]@[host] "[command]"
```
**If no keys exist, help user create them:**
```bash
# All platforms (works in PowerShell, bash, zsh)
ssh-keygen -t ed25519 -C "user@example.com"
# Copy public key to server (if ssh-copy-id available)
ssh-copy-id -i ~/.ssh/id_ed25519.pub [username]@[host]
# Or manually append to server's authorized_keys
cat ~/.ssh/id_ed25519.pub | ssh [username]@[host] "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"
```
### 2. Password Authentication
**IMPORTANT: Password auth handling differs by platform.**
#### Windows Approach
Windows OpenSSH doesn't support `sshpass`. Use one of these methods:
**Option A: Use the included Python SSH helper (RECOMMENDED)**
```powershell
# Uses paramiko library for cross-platform SSH
python scripts/ssh_helper.py --host [host] --user [username] --password [password] --command "[command]"
```
**Option B: Interactive SSH (user types password)**
```powershell
# This will prompt for password interactively
ssh -o StrictHostKeyChecking=accept-new [username]@[host] "[command]"
```
**Option C: Use PuTTY's plink (if installed)**
```powershell
# plink can accept password via echo (less secure)
echo [password] | plink -ssh -pw [password] [username]@[host] "[command]"
```
#### macOS/Linux Approach
**Option A: Use sshpass (if available)**
```bash
# Check if sshpass is installed
which sshpass
# If installed, use it
sshpass -p '[password]' ssh -o StrictHostKeyChecking=accept-new [username]@[host] "[command]"
```
**Option B: Use the Python SSH helper**
```bash
python3 scripts/ssh_helper.py --host [host] --user [username] --password [password] --command "[command]"
```
**Option C: Install sshpass**
```bash
# Ubuntu/Debian
sudo apt-get install sshpass
# macOS (with Homebrew)
brew install hudochenkov/sshpass/sshpass
# Then use sshpass commands
```
---
## Session Credential Management
**CRITICAL: One-Time Credential Collection**
When the user first requests an SSH operation, collect credentials ONCE:
```
I need SSH connection details. Please provide:
1. **Host/IP Address**: (e.g., 192.168.1.100 or server.example.com)
2. **Username**: (e.g., root, admin, ubuntu)
3. **Authentication Method**:
- SSH Key (recommended) - just provide path if not default
- Password
4. **Port** (optional): Default is 22
Example response:
- Host: 192.168.1.100
- Username: admin
- Auth: SSH Key (default location) OR Password: mypassword123
- Port: 22
```
After receiving credentials:
- Store them in working memory for the session
- Detect the operating system and choose appropriate SSH method
- Use credentials for ALL subsequent operations without re-prompting
- NEVER write credentials to files or logs
---
## Cross-Platform Command Reference
### Remote Command Execution
**With SSH Keys (All Platforms):**
```bash
ssh -o StrictHostKeyChecking=accept-new -o ConnectTimeout=30 [username]@[host] "[command]"
```
**With Password (Platform-Specific):**
```bash
# macOS/Linux with sshpass
sshpass -p '[password]' ssh -o StrictHostKeyChecking=accept-new [username]@[host] "[command]"
# All platforms with Python helper
python scripts/ssh_helper.py --host [host] --user [username] --password "[password]" --command "[command]"
```
### File Transfer (SCP)
**Upload file:**
```bash
# With keys (all platforms)
scp -o StrictHostKeyChecking=accept-new [local_file] [username]@[host]:[remote_path]
# With password (macOS/Linux)
sshpass -p '[password]' scp -o StrictHostKeyChecking=accept-new [local_file] [username]@[host]:[remote_path]
# With Python helper (all platforms)
python scripts/ssh_helper.py --host [host] --user [username] --password "[password]" --upload [local_file] --remote-path [remote_path]
```
**Download file:**
```bash
# With keys (all platforms)
scp -o StrictHostKeyChecking=accept-new [username]@[host]:[remote_file] [local_path]
# With password (macOS/Linux)
sshpass -p '[password]' scp -o StrictHostKeyChecking=accept-new [username]@[host]:[remote_file] [local_path]
# With Python helper (all platforms)
python scripts/ssh_helper.py --host [host] --user [username] --password "[password]" --download [remote_file] --local-path [local_path]
```
### Port Forwarding
**Local Port Forwarding (-L):**
```bash
# Access remote service on local port (all platforms with keys)
ssh -L [local_port]:localhost:[remote_port] [username]@[host]
# Example: Access remote MySQL (3306) on local port 3307
ssh -L 3307:localhost:3306 [username]@[host]
```
**Remote Port Forwarding (-R):**
```bash
# Expose local service to remote (all platforms with keys)
ssh -R [remote_port]:localhost:[local_port] [username]@[host]
```
**Dynamic Port Forwarding (SOCKS Proxy):**
```bash
ssh -D [local_port] [username]@[host]
```
---
## Server Administration Tasks
### System Information
```bash
# Check system info
ssh user@host "uname -a && cat /etc/os-release"
# Check disk space
ssh user@host "df -h"
# Check memory usage
ssh user@host "free -h"
# Check running processes
ssh user@host "ps aux --sort=-%mem | head -20"
# Check system load
ssh user@host "uptime && top -bn1 | head -15"
```
### Service Management (systemd)
```bash
# Check service status
ssh user@host "systemctl status [service_name]"
# Start/stop/restart service
ssh user@host "sudo systemctl start|stop|restart [service_name]"
# View service logs
ssh user@host "journalctl -u [service_name] -n 50 --no-pager"
```
### Log Analysis
```bash
# View recent system logs
ssh user@host "sudo tail -100 /var/log/syslog"
# Search logs for errors
ssh user@host "sudo grep -i error /var/log/syslog | tail -50"
# View auth logs
ssh user@host "sudo tail -50 /var/log/auth.log"
```
### Network Diagnostics
```bash
# Check listening ports
ssh user@host "ss -tulpn"
# Check network connections
ssh user@host "netstat -an | grep ESTABLISHED"
# Test connectivity
ssh user@host "ping -c 3 [target] && traceroute [target]"
```
---
## Instructions for Claude
1. **Detect Platform First**: Check if running on Windows, macOS, or Linux to choose the right SSH approach.
2. **Prefer SSH Keys**: Always check for and recommend SSH key authentication first.
3. **First SSH Request**: Prompt for credentials using the format above. Wait for response before proceeding.
4. **Store Credentials**: Remember credentials for the entire session. DO NOT ask again.
5. **Choose Correct Method**:
- If SSH keys are available → Use standard SSH commands
- If password auth on Windows → Use Python helper script or prompt user
- If password auth on macOS/Linux → Try sshpass, fall back to Python helper
6. **Handle Errors**: If authentication fails, inform user and suggest alternatives:
- Set up SSH keys
- Install sshpass (macOS/Linux)
- Use the Python helper script
7. **Security First**:
- Never echo passwords in command output
- Use `-o StrictHostKeyChecking=accept-new` for first connections
- Recommend SSH keys over passwords
8. **Custom Port**: Add `-p [port]` to SSH/SFTP or `-P [port]` to SCP commands.
---
## Configuration Options
| Option | SSH Flag | Description |
| ------------- | ------------------------- | ------------------------- |
| Custom port | `-p [port]` | Non-standard SSH port |
| Timeout | `-o ConnectTimeout=[sec]` | Connection timeout |
| Compression | `-C` | Enable compression |
| Verbose | `-v` or `-vv` | Debug output |
| Identity file | `-i [path]` | Specific SSH key |
| Batch mode | `-o BatchMode=yes` | Fail instead of prompting |
---
## Troubleshooting
| Issue | Platform | Solution |
| ---------------------------- | -------- | ------------------------------------------------------------- |
| `sshpass: command not found` | Windows | Use Python helper or set up SSH keys |
| `sshpass: command not found` | macOS | `brew install hudochenkov/sshpass/sshpass` |
| `sshpass: command not found` | Linux | `apt install sshpass` or `yum install sshpass` |
| Permission denied | All | Check username/password/key, verify server allows auth method |
| Connection refused | All | Verify host/port, check if SSH service running |
| Host key changed | All | Server reinstalled - verify and update known_hosts |
| Connection timeout | All | Check network, firewall rules |
| `paramiko` not found | All | `pip install paramiko` for Python helper |
---
## When to Use This Skill
- "SSH into my server at 192.168.1.100"
- "Connect to my remote machine"
- "Run a command on the server"
- "Upload/download files to/from the server"
- "Set up port forwarding"
- "Create an SSH tunnel"
- "Check server status"
- "Restart a service on the server"
- "View server logs"
## When NOT to Use This Skill
- Local file operations (no SSH needed)
- Cloud provider API operations (use their CLIs)
- Database client connections (use database tools)
---
## Examples
### Example 1: First Connection with Keys
**User:** "SSH into my server and check disk space"
**Claude:**
1. Prompts for connection details
2. User provides: Host: 10.0.0.5, Username: admin, Auth: SSH Key
3. Executes: `ssh -o StrictHostKeyChecking=accept-new admin@10.0.0.5 "df -h"`
4. Returns disk space information
### Example 2: Windows with Password
**User:** "Connect to 192.168.1.100 with password and restart nginx"
**Claude:**
1. Detects Windows platform
2. Uses Python helper: `python scripts/ssh_helper.py --host 192.168.1.100 --user admin --password "secret" --command "sudo systemctl restart nginx"`
3. Returns result
### Example 3: macOS/Linux with Password
**User:** "SSH to my server with password"
**Claude:**
1. Detects macOS/Linux
2. Checks for sshpass: `which sshpass`
3. If available: `sshpass -p 'password' ssh admin@host "command"`
4. If not: Uses Python helper or suggests installing sshpass
---
## Python Helper Script
The `scripts/ssh_helper.py` provides cross-platform SSH with password authentication.
**Install dependencies:**
```bash
pip install paramiko
```
**Usage:**
```bash
# Run command
python scripts/ssh_helper.py --host 192.168.1.100 --user admin --password "secret" --command "df -h"
# Upload file
python scripts/ssh_helper.py --host 192.168.1.100 --user admin --password "secret" --upload ./local.txt --remote-path /tmp/remote.txt
# Download file
python scripts/ssh_helper.py --host 192.168.1.100 --user admin --password "secret" --download /var/log/syslog --local-path ./syslog.txt
```
See `scripts/ssh_helper.py` for full implementation.
---
## Version History
- v2.0.0 (2025-12-17): Cross-platform rewrite - Windows, macOS, Linux support
- v1.0.0 (2025-12-17): Initial release