SSH Command Execution API
The SSH Command Execution API allows you to securely execute approved diagnostic commands on your Scalelite infrastructure for monitoring and troubleshooting purposes.
Security Notice: Only pre-approved commands from a security whitelist can be executed. Dangerous operations like rm, shutdown, passwd, and command chaining are blocked.
Endpoints
1. Execute Command
POST /api/v1/instances/{instance_id}/ssh/execute2. Get Command History
GET /api/v1/instances/{instance_id}/ssh/history3. Get Command Templates
GET /api/v1/ssh/templatesAuthentication
All endpoints require API key authentication:
X-API-Key: your-api-key-hereExecute Command - Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| command | string | Yes | The command to execute (must be whitelisted) |
| target | string | No | Target: scalelite (default) or BBB server ID |
| timeout | integer | No | Timeout in seconds (default: 30, max: 120) |
Allowed Commands (Whitelist)
| Category | Commands |
|---|---|
| Docker | docker ps, docker logs, docker stats --no-stream |
| System | df -h, free -m, uptime, top -b -n 1 |
| Services | systemctl status, systemctl is-active |
| Network | netstat -tlnp, ss -tlnp, ping -c 3 |
| System Info | cat /proc/cpuinfo, cat /proc/meminfo, hostname |
| BBB | bbb-conf --status, bbb-conf --check, bbb-conf --secret |
Blocked Commands
| Pattern | Reason |
|---|---|
| rm -rf, rm -r | Recursive deletion - data loss risk |
| shutdown, reboot, halt | System control - service disruption |
| passwd, useradd, userdel | User management - security risk |
| chmod 777, chown | Permission changes - security risk |
| ; and and or pipe | Command chaining - injection risk |
Error Responses
| Status | Description |
|---|---|
| 400 | Command not allowed (blocked by security policy) |
| 401 | Invalid or missing API key |
| 403 | API key does not have SSH permissions |
| 404 | Instance or target server not found |
| 408 | Command execution timed out |
| 500 | SSH connection or execution failed |
Audit Logging
All command executions are logged to the audit trail with: user, API key, command, target, timestamp, exit code, and output (truncated if exceeds 10KB). Audit logs are retained for 90 days.