Check command results via API

After you have executed a Run Command on your server, you need the information of the current progress of the queued job as well as the output of the command itself.

The following documentation describes how to check the results of the commands and what kind of limitations currently exist.

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 how to run a command

How to get the results of all executed commands on your server

You need to provide the following information in your API requests:

• projectId
• serverId

Use the following GET request to obtain an overview of all commands that have been sent to your server so far. You can use this request if you lost the commandID of a Run Command job that you want to check.

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

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

Example output of the GET request:

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

{
  "items": [
    {
      "id": 775,
      "startedAt": "2024-02-08T16:22:29Z",
      "finishedAt": "2024-02-08T16:22:48Z",
      "status": "completed",
      "commandTemplateId": "windowsResetPassword",
      "commandTemplateTitle": "Reset Password"
    }
  ]
}

How to get the results of a specific Run Command

If you want to check the result of a specific command (for example, the last command that you executed), use the commandID from the POST request output of the corresponding API request (Run a command via API) and add this commandID to the GET request shown below.

Provide the following information in your API requests:

• projectId
• serverId
• commandId

Use the following GET request to obtain more information about the specific command:

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

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

Example output of commandID 775 after the successfully completed execution of the Run Command (Command Template > ResetPassword):

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

{
  "id": 775,
  "startedAt": "2024-02-08T16:22:29Z",
  "finishedAt": "2024-02-08T16:22:48Z",
  "output": "Password for user 'testuser' has been reset successfully.\n",
  "exitCode": 0,
  "status": "completed",
  "commandTemplateId": "windowsResetPassword",
  "commandTemplateTitle": "Reset Password",
  "script": "param (\r\n [Parameter(Mandatory = $true)]\r\n [ValidateNotNullOrEmpty()]\r\n [string]$Username,\r\n\r\n [Parameter(Mandatory = $true)]\r\n [ValidateNotNullOrEmpty()]\r\n [string]$Password\r\n)\r\n\r\nfunction Reset-LocalUserPassword {\r\n [CmdletBinding()]\r\n param(\r\n [Parameter(Mandatory = $true)]\r\n [ValidateNotNullOrEmpty()]\r\n [string]$Username,\r\n\r\n [Parameter(Mandatory = $true)]\r\n [ValidateNotNullOrEmpty()]\r\n [string]$Password\r\n )\r\n\r\n$complexityRequirementsUrl =\r\n\"https://docs.stackit.cloud/stackit/en/security-settings-windows-63182010.html\"\r\n$minPasswordLength = 14\r\n$complexityRequirements = @\"\r\nFailed to set password for user '$Username'. The password does not meet the complexity requirements.\r\nPasswords must meet the following complexity requirements:\r\n- Passwords may not contain the user's samAccountName (Account Name) value or entire displayName (Full Name value). Both checks aren't case-sensitive.\r\n- The password must contain characters from at least three of the following categories:\r\n - Uppercase letters of European languages (A through Z, with diacritic marks, Greek, and Cyrillic characters)\r\n - Lowercase letters of European languages (a through z, sharp-s, with diacritic marks, Greek, and Cyrillic characters)\r\n - Base 10 digits (0 through 9)\r\n - Non-alphanumeric characters (special characters): ~!@#$%^&*_-+=`|\(){}[]:;\"'<>,.?/\r\n - Any Unicode character that's categorized as an alphabetic character but isn't uppercase or lowercase. This group includes Unicode characters from Asian languages.\r\n- The minimum password length is $minPasswordLength characters.\r\n\r\nPlease refer to the password complexity requirements at $complexityRequirementsUrl for more information.\r\n\"@\r\n\r\n # Check if the local user exists\r\n $user = Get-LocalUser -Name $Username -ErrorAction SilentlyContinue\r\n if ($user -eq $null) {\r\n # Create a new local user\r\n $minPasswordLength = 14\r\n $regexPattern = \"^(?=.*\\d)(?=.*[A-Z])(?=.*[a-z])(?=.*[^A-Za-z0-9]).{$minPasswordLength,}$\"\r\n if ($Password -match $regexPattern) {\r\n try {\r\n $securePassword = ConvertTo-SecureString -String $Password -AsPlainText -Force\r\n $newUserParams = @{\r\n 'Name' = $Username\r\n 'Password' = $securePassword\r\n 'ErrorAction' = 'Stop'\r\n }\r\n $newUser = New-LocalUser @newUserParams\r\n Write-Host \"User '$Username' created successfully.\"\r\n }\r\n catch {\r\n\r\n Write-Error \"Failed to create user '$Username'. $_\"\r\n\r\n return\r\n }\r\n\r\n # Add the user to the Administrators group\r\n try {\r\n Add-LocalGroupMember -Group 'Administrators' -Member $Username -ErrorAction Stop\r\n Write-Host \"User '$Username' has been added to the Administrators group.\"\r\n }\r\n catch {\r\n Write-Error \"Failed to add user '$Username' to the Administrators group. $_\"\r\n return\r\n }\r\n\r\n # Add the user to the Remote Desktop Users group\r\n try {\r\n Add-LocalGroupMember -Group 'Remote Desktop Users' -Member $Username -ErrorAction Stop\r\n Write-Host \"User '$Username' has been added to the Remote Desktop Users group.\"\r\n }\r\n catch {\r\n Write-Error \"Failed to add user '$Username' to the Remote Desktop Users group. $_\"\r\n return\r\n }\r\n }\r\n else {\r\n\r\n Write-Host $complexityRequirements -ForegroundColor Red\r\n }\r\n\r\n return\r\n }\r\n\r\n # Reset the user's password with custom complexity requirements\r\n $minPasswordLength = 14\r\n $regexPattern = \"^(?=.*\\d)(?=.*[A-Z])(?=.*[a-z])(?=.*[^A-Za-z0-9]).{$minPasswordLength,}$\"\r\n if ($Password -match $regexPattern) {\r\n try {\r\n $securePassword = ConvertTo-SecureString -String $Password -AsPlainText -Force\r\n $user | Set-LocalUser -Password $securePassword -ErrorAction Stop\r\n Write-Host \"Password for user '$Username' has been reset successfully.\"\r\n }\r\n catch [System.UnauthorizedAccessException] {\r\n Write-Error \"Access denied. Make sure to run the script with elevated privileges.\"\r\n }\r\n catch {\r\n Write-Error \"Failed to reset password for user '$Username'. $_\"\r\n }\r\n }\r\n else {\r\n\r\n Write-Host $complexityRequirements -ForegroundColor Red\r\n }\r\n}\r\n\r\nReset-LocalUserPassword -Username $Username -Password $Password"
}

Please keep in mind that the maximum output size of your script results is limited to 10.000 characters.

Destringifiy the output of your Run Command result

Note that the output of the executed example script above is in a stringified (JSON string) format, which might be hard to read. If you need the output in a more readable form or want to process it further, you can de-stringify it.

This is what stringified output looks like:

"Current physical memory usage for host: testserver\n2.02 GB RAM in Use (25.31%)\n5.97 GB RAM Available (74.69%)\n8.00 GB RAM Total (100%)\n"

After converting it to a human-readable form, the same output looks like this:

Current physical memory usage for host: testserver
2.02 GB RAM in Use (25.31%)
5.97 GB RAM Available (74.69%)
8.00 GB RAM Total (100%)

To convert stringyfied content into human readable form, there are several possibilites:

Linux (destringify via bash)

1. Save this bash destringification script to the file destringify.sh:

   #!/bin/bash
   ### Please enter the full filepath of your created input file below
   input_file="input"
   
   ### Read the stringified content from the input file
   stringified_content=$(cat "$input_file")
   
   ### Destringify the content using sed
   destringified_content=$(echo -e "$stringified_content" | sed 's/\\r/\r/g; s/\\n/\n/g')
   
   ### Print the destringified content to the console
   echo -e "$destringified_content"
   
   ### Output the destringified content to a separate file
   output_file="${input_file}_destringified"
   echo -e "$destringified_content" > "$output_file"

2. Make the destringification script file executable:

   chmod +x destringify.sh

3. Create a file named input containing the stringified run command output value.

4. Execute the destringify script in the same folder as the input file.
   Alternatively, you can add the path of the input file in the script: input_file="/path/to/input".

   The destringify script reads the stringified content of the “input” file and destringifies it by substituting the escape characters. The result is displayed on the console and also written into an output file named input_destringified in the same folder as the input file.

Windows (destringify via PowerShell)

1. Open a PowerShell ISE session and paste the script into it.

   ## Enter the full path and file name of your created input file below
   $InputContent = "C:\temp\input_content.txt"
   $OutputContent = "C:\temp\output_content.txt"
   
   ### Reading the stringified content from the input file
   $GetInput = Get-Content -Path $InputContent
   
   ### Replacing escape sequences with corresponding characters
   $destringifiedContent = $GetInput -replace "\\r", "`r" -replace "\\n", "`n"
   
   ### Printing the destringified content to the console
   Write-Host $destringifiedContent
   
   ### Writing the destringified content to a separate file
   $destringifiedContent | Out-File -FilePath $OutputContent

2. Create a new text file C:\temp\input_content.txt containing the stringified content.

3. Run the script.

   The script reads the stringified content of the input_content.txt file and destringifies it by replacing the escape characters. The result is displayed on the console and also written into an output file named output_content.txt in the same folder as the input file.

Using online tools

There are online tools available for destringification.