Remote Terminal

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

ssh user@hostname "command"

Using SSH Config Aliases

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

ssh <alias> "command"

With Password (using sshpass)

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

Connection Methods

1. SSH (Recommended)

Key-based authentication (most secure):

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

Using SSH config aliases:

# 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:

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

2. Telnet

# 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:

# 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:

[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

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

Docker Management

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

Service Management

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

File Operations

# 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

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:

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:

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

Using Parallel SSH

For larger fleets:

# 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:

{
  "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

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

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

Troubleshooting

Connection Refused

# 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

# 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

# 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:

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

Table Output

For commands like docker ps, ps aux:

# 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