SYS module

POST api/v2/jobs/rvc

Starts a SC//Reliant™ Virtual Controller (RVC) job for the SYS module. This provides a way to retrieve system information, like memory usage, running processes, temperature, etc, from a target. 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.

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.report`	Retrieves a combined report of the system information returned by the other SYS methods, including uptime, timezone, CPU load, memory, network, sensors, storage, crontab, hardware, and operating system details, plus summaries of the cluster, Docker, and KVM status on the host. Each section of the report is returned as an object with a `name` and `content` field.
`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.
`sys.uptime`	Retrieves how long the host has been running, as the time the host started (`since`) and a human-readable duration (`humanized`). This is similar to running `uptime` on a host.

Common request parameters

The RVC SYS methods accept the following common request parameters as data in JSON format. These request parameters specify the RVC module and method to use as well as details about the target.

Parameter	Type	Description	Required
`method`	String	The RVC action to start. This value is specified as a combination of the RVC module and method. For example, to use the SYS method for retrieving the system time you would specify the `sys` module and the `time` method combined as `sys.time`.	Yes
`params`	String	The additional parameters that scope the RVC job request. This request parameter is only used with the `sys.process` method.	No
`hostnames`	String array	The list of node hostnames on which to run the RVC job.	Dependent. Only if no node group or saved filter is provided.
`node_group_name`	String	The name of the node group on which to run the RVC job. The RVC job will run on all nodes that are members of the node group.	Dependent. Only if no hostnames or saved filter is provided.
`node_group_id`	Integer	The ID of the node group on which to run the RVC job. The RVC job will run on all nodes that are members of the node group.	Dependent. Only if no hostnames or saved filter is provided.
`saved_filter_name`	String	The name of the saved filter on which to run the RVC job. The RVC job will run on all nodes that match the saved filter.	Dependent. Only if no hostnames or node group is provided.
`saved_filter_id`	Integer	The ID of the saved filter on which to run the RVC job. The RVC job will run on all nodes that match the saved filter.	Dependent. Only if no hostnames or node group is provided.

Response syntax

When the hostnames request parameter is used, the following response syntax is received.

{
    "id": integer,
    "type": "RVC3",
    "status": "string",
    "message": "string",
    "trigged_by": "string",
    "parameters": {
        "method": "sys.<method>",
        "hostnames": [
            "string",
            "string"
        ]
    },
    "time_started": "timestamp"
}

When the node group or saved filter request parameters are used, the following response syntax is received.

{
    "id": integer,
    "type": "RVC3",
    "status": "string",
    "message": "string",
    "trigged_by": "string",
    "parameters": {
        "method": "sys.<method>",
        "node_group_name": "string",
        "node_group_id": integer,
        "saved_filter_name": "string",
        "saved_filter_id": integer
    },
    "time_started": "timestamp"
}

Common response parameters

If the action is successful, an HTTP 200 response is returned. The following data is returned in JSON format.

Field	Type	Description
`id`	Integer	The ID of the RVC job.
`type`	String	The type of RVC job. For RVC jobs, it is `RVC3`.
`status`	String	The status of the job.
`message`	String	This field is reserved for internal use.
`trigged_by`	String	The username of the person who initiated the job.
`parameters`	String	The request parameters indicating the hostnames, node groups, or saved filters the RVC job ran on.
`time_started`	Timestamp	The timestamp indicating when the job started. The timestamp is given in ISO 8601 UTC datetime format.

Examples

To see API examples for the SYS module, see SYS Module Examples.