SSH Server API Documentation

Creating SSH commands

In the web panel navigate to the SSH Server API menu.

There you can create an SSH command using the Create button.

Fields

  • Active

    Self explanatory

  • Allow STDIN

    Allows the API parameter STDIN which is passed as the Standart input ( STDIN ) to the command

  • Send SIGHUP on timeout

    Terminates the program using the SIGHUP signal on timeout. When disabled it wont terminate the program, so it will run indefinitely

  • Timeout

    Timeout in seconds, best practice is to have a timeout, that is a bit higher than the command execution time

  • Name

    A name just for a reference

  • SSH Remote User

    Overwrites the default server user. Fallbacks to the default server user if this one is missing on the server.

  • API Token

    The system generates an API token that is only valid for this particular command.

  • Command

    The command that will be executed on API call. See the Input variables and Examples section for more information

  • IP Allow list

    When empty every IP is allowed to execute the command, else only the specified IP addresses will be allowed. It supports single IP, networks and comma separated list - 192.168.0.1/24,192.168.1.1

  • Server Groups

    The command will be executed on every server group specified. Note that every server must have the API server option activated and a default user

Connecting to the REST API

  • Use the API Token for every command or any of the global Management API keys
  • The URI is /api/run/$ID where $ID is the API command ID - you can get it from the SSH Server API list menu
  • Use POST to send the JSON
  • A JSON object is required even if there are no input fields, so DONT send empty POST requests
  • The async API is still WIP
FLUXARK_API_KEY='1vwAFfL3T42bhLJA52rqZEDFfgJLZXyuR'
curl https://localhost/api/run/8 \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $FLUXARK_API_KEY" \
  -d '{
    "param": "file.txt",
    "STDIN": 666
  }'

JSON output

  • You can have output from multiple servers aggregated, just like the example below
  • Note that every server must finish or timeout executing it's command before returning the result

Command success

[
  {
    "exit-code": 0,
    "stdout": "",
    "started": 1725875532.674,
    "elapsed": 0.486,
    "ip_addr": "127.0.0.1",
    "status": "FINISHED",
    "stderr": "",
    "finished": 1725875533.16,
    "server-id": 5
  },
  {
    "exit-code": 0,
    "stdout": "",
    "started": 1725875532.674,
    "elapsed": 0.486,
    "ip_addr": "127.0.0.2",
    "status": "FINISHED",
    "stderr": "",
    "finished": 1725875533.16,
    "server-id": 6
  }
]

Command failure

  • The command exited with code 3, so that is the indicator that is a failure
[
  {
    "exit-code": 3,
    "finished": 1725875717.739,
    "server-id": 5,
    "elapsed": 0.446,
    "stdout": "FAILED\n",
    "ip_addr": "127.0.0.1",
    "status": "FINISHED",
    "stderr": "",
    "started": 1725875717.293
  }
]

Command timeout

  • It will return both STDOUT and STDERR if any before the timeout
[
  {
    "ip_addr": "127.0.0.1",
    "stderr": "some error",
    "exit-code": 0,
    "started": 1725876129.826,
    "server-id": 5,
    "stdout": "",
    "status": "TIMEOUTED",
    "elapsed": 3.438,
    "finished": 1725876133.264
  }
]

Input variables

In the JSON input every parameter can be used as a placeholder in the API command field, except STDIN.

Special variables

  • STDIN Pass this data to the command Standart Input
  • DRY Just return the composed command after input interpolation, Must be true/false or 1/0

Example

{ "param": "file.txt", "STDIN" => 666 }

Can be combined with the API command

cd test/; cat - > {{f-'param'}}

will create a file file.txt in the directory test/ with the content of 666. The exact command generated is

cd test/; cat - > 'file.txt'

The returned API data will be

[
  {
    "finished": 1725802237.577,
    "elapsed": 0.474,
    "stdout": "",
    "stderr": "",
    "started": 1725802237.103,
    "server-id": 5,
    "status": "FINISHED",
    "ip_addr": "127.0.0.1",
    "exit-code": 0
  }
]

Variables interpolation

Sanitize

{{{param}}} all placeholders with triple braces means sanitization - escapes special chars with \ backslash or removes characters

Raw

{{param}} double braces - no sanitization

Placeholders

  • {{param}} No variable sanitization - NOT RECOMMENDED
  • {{'param'}} No sanitization, but encloses the data with single quotes
  • {{"param"}} No sanitization, but encloses the data with double quotes
  • {{Q-'param'}} Puts the string in single quotes and escapes single quotes eg. data'test -> 'data'\''test'
  • {{f-param}} like Q-'param', but removes all forward slashes (/) - Usefull for filenames eg ../f'i$le.txt -> '..fi'\''i$le.txt'
  • {{{param}}} Removes new line and escapes special symbols like $!'" etc. with \ ( backslash )
  • {{{'param'}}} Sanitizes the data and encloses it in single quotes eg. data'test -> 'data\'test'
  • {{{"param"}}} Sanitizes the data and encloses it in double quotes eg. data'test -> "data\'test"
  • {{{q-'param'}}} Puts the string in single quotes and escapes the data eg. dat$a'test -> 'dat\$a'\''test'
  • {{{qq-'param'}}} Puts the string in single quotes and escapes the data eg. data'test -> '\''data\'\''test'\''
  • {{{q-param}}} Same as abouve without the quotes
  • {{{d-param}}} Removes all non-digits eg. asd123 -> 123
  • {{{d-'param'}}}} Removes all non-digits and single quotes the input eg. asd123 -> '123'
  • {{{s-param}}} Removes all non alphanumeric characters ( like a-z, 0-9, _ - \w in regex including localized letters like Я )
  • {{{s-'param'}}} Same as above but quotes the data

Note that if you want to pass complex data, you can use the STDIN parameter in the API and the data will be passed to the command's STDIN

Example commands

Create file using STDIN as the file data

  • Input JSON

    { "param": "file.txt", "STDIN": 666 }

  • Command

    cd test/; cat - > {{f-'param'}}

  • Result

    Creates a file test/file.txt with the content '666'

Get all non-system users from Linux

  • Input JSON

    {}

  • Command

    awk -F: '($3>=1000)&&($1!="nobody"){print $1}' /etc/passwd

  • Result - returns all the users with GID > 1000 separated by new line in the stdout field

    user1\nuser2

Common errors

  • Remote channel is closed you are using STDIN as argument, but the program never consumed it's content