Restore a KVM virtual machine to a snapshot on a target

POST api/v2/jobs/rvc '{"method":"kvm.snapshot_restore","params":{"hostname":"<kvm_hostname>","snapshot":"<snapshot_name>"},"hostnames":["<node_hostname>"]}'

Starts a SC//Reliant™ Virtual Controller (RVC) job to restore a KVM virtual machine on one or more targets to one of its snapshots. The virtual machine is restarted as part of the operation and briefly reports a paused status. The available targets are a node, node group, or saved filter. The 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.

Important: In RVC 3.13.0, this method puts the cluster in maintenance mode and does not take it out of maintenance mode when it finishes. While the cluster is in maintenance mode, no cluster resources fail over. After the operation finishes, check maintenance mode with cluster.maintenance_mode? and turn it off with cluster.disable_maintenance_mode.

Note: This method runs in the background. The job finishes as soon as the operation starts, and its payload only confirms that the operation was started. To confirm that the operation completed, wait until rvc.busy returns an empty list and kvm.status returns running. For more information, see Troubleshooting RVC jobs.

In order to perform this action, the following conditions must be met:

Must have the Remote Job Execution feature turned on at the site level.
The user must have the following capabilities:
- Create and Update a RVC job
- Call KVM state altering methods

Request syntax

post api/v2/jobs/rvc '{"method":"kvm.snapshot_restore","params":{"hostname":"<kvm_hostname>","snapshot":"<snapshot_name>"},"hostnames":["<node_hostname>"]}'

Request parameters

The request accepts the following data in JSON format.

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 restore a KVM virtual machine to a snapshot you would specify the `kvm` module and the `snapshot_restore` method combined as `kvm.snapshot_restore`.	Yes
`params`	Object	The parameters for the method. For the supported parameters, see Method parameters.	Yes
`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.

Method parameters

The params object accepts the following parameters.

Parameter	Type	Description	Required	Default value
`hostname`	String	The name of the virtual machine on the node.	Yes	-
`snapshot`	String	The name of the snapshot to restore, as returned by `kvm.snapshot_list`.	Yes	-
`notify_uri`	String	A URI to which RVC sends progress messages for the operation, including a final message with its exit code.	No	`null`

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": "kvm.snapshot_restore",
        "params": {
            "hostname": "<kvm_hostname>",
            "snapshot": "<snapshot_name>"
        },
        "update_rpm": boolean,
        "hostnames": [
            "string"
        ]
    },
    "time_started": "timestamp"
}

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`	Object	The request parameters indicating the method, method parameters, and 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.

Errors

The following errors can be returned for a node in the job payload. For other errors, see Troubleshooting RVC jobs and Common errors.

Code	Message	Cause
`-32085`	`Virtual Machine <name> is busy running the <operation> operation.`	Another operation on the virtual machine has not finished. Wait until `rvc.busy` returns an empty list, then try again.
`-32086`	`Virtual Machine <name> not found on host.`	The virtual machine does not exist on the node. Run `kvm.list` to see the virtual machines on the node.

Examples

Example 1: Restore a KVM virtual machine to a snapshot on a node.

This example restores the KVM virtual machine kvm1 on the node with hostname sit0001red0 to the snapshot disk0.kvm1-2026-10-11-215908.108.

ruby api.rb <customer_code> POST api/v2/jobs/rvc '{"method":"kvm.snapshot_restore","params":{"hostname":"kvm1","snapshot":"disk0.kvm1-2026-10-11-215908.108"},"hostnames":["sit0001red0"]}'

Response

{
  "id": 1782028,
  "type": "RVC3",
  "status": "pending",
  "message": null,
  "trigged_by": "test.user",
  "parameters": {
    "method": "kvm.snapshot_restore",
    "params": {
      "hostname": "kvm1",
      "snapshot": "disk0.kvm1-2026-10-11-215908.108"
    },
    "update_rpm": true,
    "hostnames": [
      "sit0001red0"
    ]
  },
  "time_started": "2026-10-11T22:00:53Z"
}

Example 2: Retrieving the payload from the RVC job.

This example retrieves the payload from RVC job ID 1782028.

ruby api.rb <customer_code> GET "api/jobs/1782028?include_payload=true"

Response

{
  "id": 1782028,
  "type": "RVC3",
  "status": "finished",
  "message": null,
  "trigged_by": "test.user",
  "success_nodes_count": 1,
  "failed_nodes_count": 0,
  "total_nodes_count": 1,
  "parameters": {
    "method": "kvm.snapshot_restore",
    "params": {
      "hostname": "kvm1",
      "snapshot": "disk0.kvm1-2026-10-11-215908.108"
    },
    "hostnames": [
      "sit0001red0"
    ],
    "update_rpm": true
  },
  "time_started": "2026-10-11T22:00:53Z",
  "time_finished": "2026-10-11T22:00:54Z",
  "payload": {
    "sit0001red0": [
      {
        "result": "Restoring snapshot disk0.kvm1-2026-10-11-215908.108 for kvm1...",
        "timestamp": 1791756054
      }
    ]
  }
}