SYS module examples

The following are examples demonstrating the use of the SC//Reliant™ Virtual Controller (RVC) API job for the SYS module. The API response will indicate that the RVC job is created and is scheduled to run. You can use the job ID from the response to retrieve the job status and the payload details.

Required permissions

In order to perform these actions, the following conditions must be met:

Must have the Remote Job Execution feature turned on for your SC//Reliant Platform Manager tenant.
The user making the API request must have the following SC//Reliant Platform Manager capabilities:
- Create and Update a RVC job
- Call System read-only methods

Methods

The following are the available RVC methods in the SYS module. You can substitute these in any of the provided examples.

Method	Description
`sys.cpu-load`	Retrieves details about the CPU usage for each core. This method is only available when using RVC version `3.4.0` or later.
`sys.crontab`	Retrieves the crontab details. This is similar to running `sudo crontab -l` on a host.
`sys.hardware`	Retrieves system hardware information, such as the manufacturer, model, motherboard, and BIOS version. This includes details similar to running `sudo dmidecode` on a host.
`sys.memory`	Retrieves details about memory usage data, in kilobytes (KB). This is similar to running `sudo free` on a host.
`sys.network`	Retrieves details about the network interfaces and their network statistics. This is similar to running `sudo ifconfig` and `sudo netstat -i` on a host.
`sys.os`	Retrieves details about the operating system, such as the Linux distro, release version, kernel version, and architecture. This is similar to running `sudo uname -a` on a host.
`sys.process`	Retrieve a list of running processes, separated by CPU and memory usage. The list is returned in order of most to least amount of CPU and memory usage. The number of rows returned can be specified using the `params` request parameter. A maximum of `20` rows can be returned. This is similar to running `sudo top` on a host.
`sys.sensors`	Retrieves detailed sensor information. This is similar to running `sudo ipmitool sensor` on a host. This method is only available when using RVC version `3.4.0` or later.
`sys.storage`	Retrieves details about disk usage, which includes the mount point, device, and filesystem details. This is similar to running `sudo df -H` on a host.
`sys.temperature`	Retrieves thermal information for the available system components.
`sys.time`	Retrieves the system time in ISO 8601 format. This is similar to running `sudo date --iso-8601=seconds` on a host.
`sys.timezone`	Retrieves the system timezone. This is similar to running `sudo timedatectl` on a host.

Examples

Example 1: Retrieve system hardware details for a list of node hostnames.

This example starts an RVC job requesting system hardware details for a node with hostname sit0001red0.

ruby api.rb <customer_code> post api/v2/jobs/rvc '{"method":"sys.hardware","hostnames":["sit0001red0"]}'

Response

{
  "id": 1599018,
  "type": "RVC3",
  "status": "pending",
  "message": null,
  "trigged_by": "test.user",
  "parameters": {
    "method": "sys.hardware",
    "hostnames": [
      "sit0001red0"
    ]
  },
  "time_started": "2025-04-11T17:44:26Z"
}

Use the following API call to retrieve the job details, which includes the payload with the system hardware details. Ensure that you're using the job ID from the output of the previous API call when requesting the job details.

ruby api.rb <customer_code> get api/jobs/1599018\?include_payload=true

Response

{
  "id": 1599018,
  "type": "RVC3",
  "status": "finished",
  "message": null,
  "payload": {
    "sit0001red0": [
      {
        "result": {
          "bios_date": "11/22/2019",
          "board_name": "A1SRi",
          "sys_vendor": "Supermicro",
          "bios_release": "N/A",
          "bios_version": "2.2",
          "board_vendor": "Supermicro",
          "product_name": "SYS-5018A-FTN4",
          "product_family": "N/A",
          "product_version": "123456789"
        },
        "timestamp": 1744393468
      }
    ]
  },
  "trigged_by": "test.user",
  "success_nodes_count": 1,
  "failed_nodes_count": 0,
  "total_nodes_count": 1,
  "parameters": {
    "method": "sys.hardware",
    "hostnames": [
      "sit0001red0"
    ]
  },
  "time_started": "2025-04-11T17:44:26Z",
  "time_finished": "2025-04-11T17:44:27Z"
}

Example 2: Retrieve the top 3 processes using the most resources for a list of node hostnames.

This example starts an RVC job requesting the top 3 processes using the most CPU and memory resources for a node with hostname sit0001red0. You can use the rows parameter to adjust how many processes are returned, with the maximum value being 20.

ruby api.rb <customer_code> post api/v2/jobs/rvc '{"method":"sys.process","params":{"rows":3},"hostnames":["sit0001red0"]}'

Response

{
  "id": 1600018,
  "type": "RVC3",
  "status": "pending",
  "message": null,
  "trigged_by": "test.user",
  "parameters": {
    "method": "sys.process",
    "params": {
      "rows": 3
    },
    "hostnames": [
      "sit0001red0"
    ]
  },
  "time_started": "2025-04-16T18:25:47Z"
}

Use the following API call to retrieve the job details, which includes the payload with the system process details. Ensure that you're using the job ID from the output of the previous API call when requesting the job details.

ruby api.rb <customer_code> get api/jobs/1600018\?include_payload=true

Response

{
  "id": 1600018,
  "type": "RVC3",
  "status": "finished",
  "message": null,
  "payload": {
    "sit0001red0": [
      {
        "result": {
          "cpu": [
            {
              "pid": 4499,
              "user": "root",
              "command": "/opt/puppetlabs/puppet/bin/ruby /usr/bin/choria_mcollective_agent_compat.rb --config /etc/choria/choria-shim.cfg",
              "cpu_time": "0:01",
              "cpu_usage": 125,
              "memory_usage": 0.1
            },
            {
              "pid": 3062,
              "user": "haclust+",
              "command": "/usr/lib/pacemaker/cib",
              "cpu_time": "959:04",
              "cpu_usage": 3.3,
              "memory_usage": 0.1
            },
            {
              "pid": 2357,
              "user": "root",
              "command": "/usr/sbin/libvirtd",
              "cpu_time": "458:57",
              "cpu_usage": 1.6,
              "memory_usage": 0.2
            }
          ],
          "memory": [
            {
              "pid": 2361,
              "user": "root",
              "command": "/usr/local/bin/rvcd --config=/etc/rvc/rvc.yaml",
              "cpu_time": "0:57",
              "cpu_usage": 0,
              "memory_usage": 1.5
            },
            {
              "pid": 19463,
              "user": "sensu",
              "command": "mysqld",
              "cpu_time": "23:32",
              "cpu_usage": 0,
              "memory_usage": 1.3
            },
            {
              "pid": 2376,
              "user": "root",
              "command": "/usr/bin/dockerd -H unix:///var/run/docker.sock --ip-forward=true --iptables=false --ip-masq=true --log-driver syslog -G docker",
              "cpu_time": "120:18",
              "cpu_usage": 0.4,
              "memory_usage": 0.6
            }
          ]
        },
        "timestamp": 1744828033
      }
    ]
  },
  "trigged_by": "test.user",
  "success_nodes_count": 1,
  "failed_nodes_count": 0,
  "total_nodes_count": 1,
  "parameters": {
    "method": "sys.process",
    "params": {
      "rows": 3
    },
    "hostnames": [
      "sit0001red0"
    ]
  },
  "time_started": "2025-04-16T18:27:11Z",
  "time_finished": "2025-04-16T18:27:12Z"
}