Frequently Asked Question

RemoteCMD - Issue remote ssh commands and retrieve responses

Last Updated 8 days ago

Remote Command API Documentation

Version: 1.001

Overview

The Remote Command API allows you to execute SSH commands on remote servers. It provides a secure way to run commands on remote hosts through a standardised API interface.

This API can be used to retrieve information from hardware, such as routers, switches, and other devices as well as issues commands. We use this internally to talk to Draytek 39xx firewalls to pull current firewall rules and add new firewall rules, all programmatically.

Endpoint

/v2/remotecmd

Authentication

This API requires an API key for authentication. The key should be passed as X-API-Key header.

Parameters

Parameter	Description	Required
api_key	Your API authentication key	Yes
h	Host (IP address or hostname of the remote server)	Yes
p	Port number for SSH connection (default: 22)	No
un	Username for SSH authentication	Yes
pw	Password for SSH authentication	Yes
c	Command to execute on the remote server	Yes
d	Delay in seconds before command execution (default: 5)	No
t	Timeout in seconds for command execution (default: 10)	No

Response Format

The API returns data in JSON format.

Success Response

{
    "status": "success",
    "version": "1.001",
    "output": "Command output text",
    "transcript": {
        "timestamp1": "log message 1",
        "timestamp2": "log message 2",
        ...
    }
}

Error Response

{
    "status": "error",
    "version": "1.001",
    "message": "Error message",
    "transcript": {
        "timestamp1": "log message 1",
        "timestamp2": "log message 2",
        ...
    }
}

Error Messages

"No host provided" - The host parameter is missing
"No username provided" - The username parameter is missing
"No password provided" - The password parameter is missing
"No command provided" - The command parameter is missing
"Failed to execute command" - General execution failure

Example Response

{
    "status": "success",
    "version": "1.001",
    "output": "total 32\ndrwxr-xr-x  5 user group  4096 Jan 10 12:34 .\ndrwxr-xr-x 10 user group  4096 Jan  5 09:12 ..\n-rw-r--r--  1 user group  8445 Jan  9 15:23 file1.txt\n-rw-r--r--  1 user group  2312 Jan  7 11:45 file2.txt",
    "transcript": {
        "2023-01-15 14:23:45.123": "Starting SSH connection to 192.168.1.100:22",
        "2023-01-15 14:23:45.234": "Attempting to connect to 192.168.1.100:22",
        "2023-01-15 14:23:45.456": "Successfully connected to 192.168.1.100:22",
        "2023-01-15 14:23:45.567": "Server fingerprint: a1b2c3d4e5f6g7h8i9j0",
        "2023-01-15 14:23:45.678": "Attempting to authenticate as user 'admin'",
        "2023-01-15 14:23:45.789": "Successfully authenticated as admin",
        "2023-01-15 14:23:45.890": "Executing command: ls -la",
        "2023-01-15 14:23:47.123": "Shell session established",
        "2023-01-15 14:23:47.234": "Received 256 bytes of data",
        "2023-01-15 14:23:47.345": "Shell command execution completed",
        "2023-01-15 14:23:47.456": "Returning output from shell execution",
        "2023-01-15 14:23:47.567": "SSH connection closed properly"
    }
}

Notes

The API includes a transcript of the SSH session for debugging purposes.
For security reasons, passwords are not logged in the transcript.
The command execution has a maximum timeout of 30 seconds.
The API will wait for the specified timeout period after the last data is received before assuming the command has completed.

Security Considerations

Always use HTTPS when calling this API to protect sensitive credentials.
Protect the X-APi-Key from client-side exposure.
Be aware that command output is returned as-is and may contain sensitive information.