Introduction

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 and users 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).

The following restrictions are applied on the IP address source/destinations;

• Admin: should be allowed to ping/traceroute/arping from the VR, SSVM and the CPVM with very few restrictions.
• A normal user / domain admin: should only be allowed to ping/traceroute/arping out over the public network and private isolated network or VPC private tier network. In addition, user should be allowed to ping/traceroute/arping out over a private gateway and VPN gateway on a VPC VR.
• A normal user or domain admin should never be allowed to target:
  • An IP address in the management IP range.
  • An IP address in on a shared network unless the network is shared with the user account only and nobody else.
  • An IP address which is hosted on the private or management interface of the VR.

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.

API

remoteDiagnosis API will be implemented with the following parameters:

• uuid: the id of the system VM instance to execute network-utility command from.
• diagnosisTest: the type of network utility tool to run, e.g. ping, traceroute or arping.
• destinationIpAddress: the ping/arping/traceroute destination IP address.
• OPTIONAL: additional command line arguments for each utility tool.

The API will execute a script in the system VM, and return back as API response the;

• details: normal standard error/output information return by the command execution. 
• boolean: command execution results. (or change this to exit code?)

Not Doing

• UI integration