remote-terminal

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

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:

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:

Example prompts:

Step 2: Build Connection Command

Construct the appropriate SSH command based on:

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:

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/

references/

Basic SSH Connection

ssh user@hostname "command"

Using SSH Config Aliases

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

ssh  "command"

With Password (using sshpass)

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

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