This Confluence has been LDAP enabled, if you are an ASF Committer, please use your LDAP Credentials to login. Any problems file an INFRA jira ticket please.

Child pages
  • CloudStack Remote Diagnostics API
Skip to end of metadata
Go to start of metadata


This feature introduces a new API command that will improve troubleshooting of network issues on CloudStack hosted networks by executing network-utility commands (ping, traceroute, arping) remotely on system VMs. 

Feature Specification

For troubleshooting purposes, CloudStack administrators may wish to execute network utility commands remotely on system VMs, or request system VMs to ping/traceroute/arping to specific addresses over specific interfaces. An API command to provide such functionalities is being developed without altering any existing APIs. The targeted system VMs for this feature are the Virtual Router (VR), Secondary Storage VM (SSVM) and the Console Proxy VM (CPVM).

Use Cases

1. An admin wants to test if the SSVM can reach a web server in case of download to Secondary storage failures.

2. Ping an outside web server from the VR in case the VM is unable to get data in or out.

3. Admin might also want to know which interfaces are being used for communication between VMs.


The runDiagnostics API command makes use of the CloudStack Agents framework to run this commands on system VMs using the following algorithm;

  • The user provides the instance ID to be targeted, the type of diagnostics command and lastly, the IP/Domain address to test connection to.
  • API uses the instance ID parameter to find the host in which the VM instance is running from.
  • The diagnostics command and IP/Domain address are passed to this host as commands through the AgentManager.
  • The AgentManager then runs the command as a python script that accepts the command type and address as input arguments.
  • The execution details are returned to the AgentManager and are further parsed, prepared and returned back to the user as API response.
  • The API response contains the stdoutstderr and exitcode
  • In case of error, the stderr is populated with error details and the stdout is returned as empty and vice-versa.

Example output below using cloudmonkey to test with an SSVM;

UI Integration

API has been integrated into the UI and appears in both the hover menu and the tabs menu for both system VMs and the VR.

  • Supported diagnostics type are pre-populated and show up in a drop-down menu.
  • Destination is provided as user input string.
  • Optionla paramas are also provided as user input string.

Example user input form

Example output from the above user input;