Run a command via API

When everything is set up, you can start using the Run Command feature.

This page contains:

• How to remotely run a command on your server
• How to use scripts with arguments in your API request
• What are the limits of the script content
• What type of scripts can be executed on Linux
• How to inject your own custom scripts into your server, which allows you to fully control the server without the need to be logged in

Prerequisites

• Swagger API definition for the STACKIT Run Commands Service API.
• You have installed the Server Agent.
• Run Command service has been enabled
• Information about available command templates: Fetch command templates via API

How to use Run Command

After you have selected your command from the Command Templates, send this command to the API via a POST request. You need to provide the following information in your API requests:

• projectId
• serverId
• commandTemplateName
• parameters (if you want to use arguments)

In the following examples we are performing different Run Commands with and without arguments.

Please note that at the first time you start the server and send a command it might take a little longer for the command to be executed.

Run Command without arguments

• This command shows the current memory usage on your server (CommandTemplate: ShowMemoryUsage):

POST https://run-command.api.eu01.stackit.cloud/v1/projects/{{projectId}}/servers/{{serverId}}/commands

{
 "commandTemplateName": "ShowMemoryUsage"
}

Swagger API definition for the STACKIT Run Commands Service API: PostCommand

Run Command with (list of) arguments

• This command resets the password or creates a user on your server (CommandTemplate: “ResetPassword”). The username and the password are supplied as arguments. Note that the password has to be entered in clear text.

POST https://run-command.api.eu01.stackit.cloud/v1/projects/{{projectId}}/servers/{{serverId}}/commands

{
  "commandTemplateName": "ResetPassword",
  "parameters": {
    "username": "testuser",
    "password": "p4s5w0rd"
  }
}

Swagger API definition for the STACKIT Run Commands Service API: PostCommand.

• This command restarts a list of services (“BITS” and “BallonService”) on your server (CommandTemplate: “ManageServices”).
  In this example you can also use other action parameters to handle your services like start, stop, suspend, enable, disable, remove, etc.
  The available parameters for each command template can vary between Windows and Linux. For detailed information refer to the command template list.

POST https://run-command.api.eu01.stackit.cloud/v1/projects/{{projectId}}/servers/{{serverId}}/commands

{
  "commandTemplateName": "ManageServices",
  "parameters": {
    "action": "restart",
    "services": "BITS,BalloonService"
  }
}

Swagger API definition for the STACKIT Run Commands Service API: PostCommand.

After sending the command

Once you have sent the API request, the command will be executed on your server by the STACKIT Server Agent as soon as possible and the API will output the commandID (“id”) of that queued job. Note down this commandID because you will need it later to refer to the corresponding Run Command, e. g. when you want to evaluate its status.

Example response of the POST request for the Run Command ResetPassword with the commandID value:

{
  "id": 775
}

How to check the status of your executed Run Command and evaluate the results is described here: Check command results via API.

Execute your own script via Run Command

You can execute your own custom scripts. Proceed like this:

• Use the commandTemplateName RunShellScript (Linux) or RunPowerShellScript (Windows).
• Stringify the script, i. e. convert it into a JSON-string.
• Provide the following information in your API requests:
  • projectId
  • serverId
  • commandTemplateName “RunShellScript” or “RunPowerShellScript”
  • parameters "script" (your stringified script content)
  • parameters "argument" (if you want to use arguments)

The maximum allowed input size of your script content is 10.000 characters.

Linux (stringify script)

You can use the processing tool jq which is available in most distributions. The following method converts the content of a provided scriptfile your\_script into a string and saves the output in the file your\_script\_stringified.

Save the script below as stringify\_script.sh and make it executable:

#!/bin/bash

### Check if a filename is provided as argument
if [ $# -eq 0 ]; then
  echo "Usage: $0 <script_filename>"
  exit 1
fi

### Check if the file exists
if [! -f "$1" ]; then
  echo "File not found: $1"
  exit 1
fi

### Read the contents of the file and escape special characters
script_contents=$(cat "$1" | sed 's/\\/\\\\/g; s/"/\\"/g; s/`/\`/g')

### Add double quotes around the script contents
script_string="\"$script_contents\""

echo $script_string

chmod +x stringify_script.sh

You can now execute your script with the following command:

./stringify_script.sh your_script_file > your_script_file_stringified

Replace your\_script\_file with the file name of the script you want to stringify. This stringify script will output the stringified version of your script to the file your\_script\_file\_stringified.

Windows (stringify script with PowerShell)

1. Open a PowerShell ISE session and paste the following script in it:

   $InputContent = "C:\temp\input_content.txt"
   $OutputContent = "C:\temp\output_content.txt"
   $GetInput = Get-Content -Path $InputContent | Out-String
   $ScriptJSON = $GetInput | ConvertTo-Json -Compress
   $ScriptJSON | Out-File -FilePath $OutputContent

2. Create a new.txt file named input_content.txt, which you can place e. g. in C:\temp.

3. Put the content you want to stringify inside the input_content.txt file and save it.

4. Run the script.

   Similar to the approach above this converts the content of the input\_content.txt file into a JSON array, compresses it and puts the resulted value into the output_content.txt file.

Using online tools

There are online tools available which stringify any input.

Examples of custom scripts

• Custom stringified Powershell script with arguments for a Windows server:

POST https://run-command.api.eu01.stackit.cloud/v1/projects/{{projectId}}/servers/{{serverId}}/commands

{
  "commandTemplateName": "RunPowerShellScript",
  "parameters": {
    "script": "#ps1\nWrite-Host $Args[0] -NoNewline\nWrite-Host \",\"-NoNewline\nWrite-Host $Args[1]",
    "arguments": "Hello World"
  }
}

• Custom stringified shell script with arguments for a linux server:

POST https://run-command.api.eu01.stackit.cloud/v1/projects/{{projectId}}/servers/{{serverId}}/commands

{
  "commandTemplateName": "RunShellScript",
  "parameters": {
    "script": "echo \"This is my custom script with arguments $1 and $2\"",
    "arguments": "Hello World"
  }
}

If you use a list with more than one argument, each argument is separated with a blank space like shown in the examples above.

Types of shell scripts that can be executed on Linux

For Linux there are different ways to execute a shell script depending on whether an argument and/or a shebang header is present.

Script with shebang header and with arguments gets executed as bash script

Example script:

#!/bin/bash
### Display a simple message with arguments
echo "Hello, $1! This is a simple bash script with $2 arguments being used"

Request Body:

POST https://run-command.api.eu01.stackit.cloud/v1/projects/{{projectId}}/servers/{{serverId}}/commands

{
  "commandTemplateName": "RunShellScript",
  "parameters": {
    "script": "#!/bin/bash\n# Display a simple message with arguments\necho \"Hello, $1! This is a simple bash script with $2 arguments being used\"",
    "arguments": "Testuser,two"
  }
}

Response of the commandID (Check command results via API):

{
  "id": 828,
  "startedAt": "2024-02-15T15:20:22Z",
  "finishedAt": "2024-02-15T15:20:35Z",
  "output": "Hello, Testuser! This is a simple bash script with two arguments being used\n",
  "exitCode": 0,
  "status": "completed",
  "commandTemplateId": "RunShellScript",
  "commandTemplateTitle": "Run Shell Script",
  "script": "#!/bin/bash\n# Display a simple message with arguments\necho \"Hello, $1! This is a simple bash script with $2 arguments being used\""
}

Script with shebang header and without arguments gets executed with the path of the given shebang interpreter

Please make sure the path to the interpreter in the shebang is correct when executing the script via Run Command. In order to run i.e. a Python script like in the example below, Python needs to be properly installed on the server before you execute the script.

Example script:

#!/bin/python3
### Display a simple message
print("Hello, world! This is a simple python script without arguments being used")

Request Body:

POST https://run-command.api.eu01.stackit.cloud/v1/projects/{{projectId}}/servers/{{serverId}}/commands

{
  "commandTemplateName": "RunShellScript",
  "parameters": {
    "script": "#!/bin/python3\n# Display a simple message\nprint(\"Hello, world! This is a simple python script without arguments being used\")"
  }
}

Response of the commandID (Check command results via API):

{
  "id": 829,
  "startedAt": "2024-02-16T09:18:31Z",
  "finishedAt": "2024-02-16T09:18:50Z",
  "output": "Hello, world! This is a simple python script without arguments being used\n",
  "exitCode": 0,
  "status": "completed",
  "commandTemplateId": "RunShellScript",
  "commandTemplateTitle": "Run Shell Script",
  "script": "#!/bin/python3\n# Display a simple message\nprint(\"Hello, world! This is a simple python script without arguments being used\")"
}

Script without shebang (and with or without arguments) gets executed as bash script

Example script:

echo "Hello World, this script is executed as a bash script"

Request Body:

POST https://run-command.api.eu01.stackit.cloud/v1/projects/{{projectId}}/servers/{{serverId}}/commands

{
  "commandTemplateName": "RunShellScript",
  "parameters": {
    "script": "echo \"Hello World, this script is executed as a bash script\""
  }
}

Response of the commandID (Check command results via API):

{
  "id": 830,
  "startedAt": "2024-02-15T15:29:35Z",
  "finishedAt": "2024-02-15T15:49:53Z",
  "output": "Hello World, this script is executed as a bash script\n",
  "exitCode": 0,
  "status": "completed",
  "commandTemplateId": "RunShellScript",
  "commandTemplateTitle": "Run Shell Script",
  "script": "echo \"Hello World, this script is executed as a bash script\""
}