remote-terminal

Remote Linux terminal control skill. Use when the user wants to (1) connect to a remote Linux server and execute commands, (2) perform SSH operations on remote hosts, (3) manage multiple remote servers, (4) run shell commands on remote machines. Triggers on phrases like "connect to server", "SSH to", "run on remote", "execute on production", "login to my server", "在服务器上执行", "远程连接", "SSH到".

Execute commands on remote Linux servers through SSH, Telnet, or web terminals. Supports password authentication, SSH keys, and SSH config aliases.

Quick Start

Basic SSH Connection

bash

ssh user@hostname "command"

Using SSH Config Aliases

If the user has ~/.ssh/config configured:

bash

ssh <alias> "command"

With Password (using sshpass)

bash

sshpass -p 'password' ssh user@hostname "command"

Connection Methods

1. SSH (Recommended)

Key-based authentication (most secure):

bash

ssh -i ~/.ssh/id_rsa user@hostname "command"

Using SSH config aliases:

bash

# Example ~/.ssh/config
Host production
    HostName 192.168.1.100
    User admin
    Port 22
    IdentityFile ~/.ssh/id_rsa

# Usage
ssh production "docker ps"

Password authentication:

bash

sshpass -p 'password' ssh -o StrictHostKeyChecking=no user@hostname "command"

2. Telnet

bash

# Using expect for interactive telnet
expect -c '
spawn telnet hostname
expect "login:"
send "username\r"
expect "Password:"
send "password\r"
expect "$ "
send "command\r"
expect "$ "
send "exit\r"
'

3. Web Terminal (ttyd, wetty)

For web-based terminals, use curl or HTTP requests to the terminal's API:

bash

# Example: ttyd WebSocket connection (requires wscat or similar)
wscat -c ws://hostname:7681/ws

Security Features

Command Confirmation

Before executing dangerous commands, ask the user to confirm:

Dangerous command patterns:

• rm -rf, rm -r, del, erase
• shutdown, reboot, poweroff, halt
• mkfs, fdisk, parted, dd
• chmod 777, chown -R
• > /dev/, truncate
• kill -9, pkill, killall
• iptables, ufw, firewall-cmd
• DROP DATABASE, DELETE FROM, TRUNCATE

Confirmation format:

⚠️ Dangerous command detected: rm -rf /var/log/* This will permanently delete files. Proceed? (yes/no)

Command Blacklist

These commands are blocked by default and require explicit user override:

• rm -rf / (entire filesystem)
• mkfs on mounted drives
• dd to primary disk
• Any command piping to /dev/sda or similar

Operation Logging

All remote commands are logged with timestamp, target host, and command:

text

[2026-03-21 15:30:45] [production] docker ps
[2026-03-21 15:31:02] [staging] systemctl restart nginx

Log location: ~/.qclaw/logs/remote-terminal.log

Workflow

Step 1: Identify Target Host

Parse the user's request to identify:

• Hostname, IP address, or SSH alias
• Username (if specified, otherwise use default or prompt)
• Connection method (SSH by default)

Example prompts:

• "Connect to production and run docker ps" → alias: production
• "SSH to 192.168.1.50, check disk space" → host: 192.168.1.50
• "On my server, restart nginx" → need to ask which server

Step 2: Build Connection Command

Construct the appropriate SSH command based on:

• Authentication method available
• Host configuration
• Whether it's interactive or one-shot

Step 3: Security Check

If command matches dangerous patterns:

1. Warn the user
2. Ask for explicit confirmation
3. If confirmed, proceed; otherwise, cancel

Step 4: Execute and Return Output

Run the command and return:

• Standard output
• Standard error (if any)
• Exit code
• Execution time

Step 5: Log Operation

Record the operation in the log file for audit trail.

Common Operations

Check System Status

bash

ssh host "uptime && free -h && df -h"

Docker Management

bash

ssh host "docker ps -a"
ssh host "docker logs container_name"
ssh host "docker restart container_name"

Service Management

bash

ssh host "systemctl status nginx"
ssh host "sudo systemctl restart nginx"
ssh host "journalctl -u nginx -f --no-pager -n 50"

File Operations

bash

# View file
ssh host "cat /var/log/nginx/error.log | tail -50"

# Copy file to local
scp user@host:/remote/path /local/path

# Copy file to remote
scp /local/path user@host:/remote/path

Process Management

bash

ssh host "ps aux | grep nginx"
ssh host "top -b -n 1 | head -20"

Interactive Sessions

For commands requiring interaction, use ssh -t for pseudo-terminal:

bash

ssh -t host "sudo nano /etc/nginx/nginx.conf"
ssh -t host "htop"

Note: Interactive sessions require the -t flag to allocate a PTY.

Multiple Hosts

Parallel Execution

Execute the same command on multiple hosts:

bash

for host in web1 web2 web3; do
  echo "=== $host ===" 
  ssh $host "uptime"
done

Using Parallel SSH

For larger fleets:

bash

# Using pssh (parallel-ssh)
pssh -h hosts.txt "uptime"

# hosts.txt format
# web1.example.com
# web2.example.com
# web3.example.com

Host Management

Store Host Information

Hosts can be stored in ~/.qclaw/workspace/memory/hosts.json:

json

{
  "hosts": {
    "production": {
      "host": "192.168.1.100",
      "user": "admin",
      "method": "ssh-key",
      "key": "~/.ssh/id_rsa",
      "tags": ["web", "critical"]
    },
    "staging": {
      "host": "staging.example.com",
      "user": "deploy",
      "method": "ssh-config",
      "alias": "staging",
      "tags": ["web", "testing"]
    }
  }
}

List Known Hosts

bash

# From SSH config
grep "^Host " ~/.ssh/config | awk '{print $2}'

# From stored hosts.json
cat ~/.qclaw/workspace/memory/hosts.json

Troubleshooting

Connection Refused

bash

# Check if host is reachable
ping hostname

# Check if SSH port is open
nc -zv hostname 22

# Try with verbose output
ssh -vvv user@hostname

Permission Denied

bash

# Check key permissions
chmod 600 ~/.ssh/id_rsa

# Try with specific key
ssh -i ~/.ssh/id_rsa user@hostname

# Check if key is added to agent
ssh-add -l
ssh-add ~/.ssh/id_rsa

Host Key Verification Failed

bash

# Remove old host key
ssh-keygen -R hostname

# Or temporarily disable check (not recommended for production)
ssh -o StrictHostKeyChecking=no user@hostname

Output Parsing

Structured Output

For commands returning JSON:

bash

ssh host "docker inspect container --format '{{json .}}'" | jq .

Table Output

For commands like docker ps, ps aux:

bash

# Return as-is for readable tables
ssh host "docker ps --format 'table {{.Names}}\t{{.Status}}'"

# Parse for structured data
ssh host "docker ps --format '{{json .}}'" | jq .

Resources

scripts/

• ssh_exec.py - Python wrapper for SSH operations with logging
• host_manager.py - Manage host configurations
• parallel_exec.py - Execute commands on multiple hosts

references/

• ssh_config_guide.md - SSH config file examples and patterns
• security_best_practices.md - Security guidelines for remote access