Create a full backup of a KVM virtual machine on a target

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

Starts a SC//Reliant™ Virtual Controller (RVC) job to create a full backup archive of a KVM virtual machine on one or more targets. The virtual machine is shut down while its disk is copied and started again before the archive is created. 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.

Before it starts, RVC checks that the target directory is under the directory configured for full backups, that the archive does not already exist, and that the partition has room for about twice the size of the virtual machine directory. If a check fails, or the backup fails later, the job payload still shows that the backup started.

Important: filename is the name of the archive only. Do not include a directory. The archive is written to the directory in target, or to the full_backup directory in the RVC configuration file if target is not set. A path in filename is accepted, but the backup fails.

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 for the final progress message with exit code 0, or check the RVC log on the node. Do not use kvm.full_backup_info for this, because it can read an archive that is still being written. 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.full_backup","params":{"hostname":"<kvm_hostname>","filename":"<archive_name>"},"hostnames":["<node_hostname>"]}'

Request parameters

The request accepts the following data in JSON format.

Method parameters

The params object accepts the following parameters.

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.full_backup",
        "params": {
            "hostname": "<kvm_hostname>",
            "filename": "<archive_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.

Errors

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

Examples

Example 1: Create a compressed full backup of a KVM virtual machine on a node.

This example creates the compressed archive kvm1_doc-test.tar.gz of the KVM virtual machine kvm1 on the node with hostname sit0001red0.

ruby api.rb <customer_code> POST api/v2/jobs/rvc '{"method":"kvm.full_backup","params":{"hostname":"kvm1","filename":"kvm1_doc-test.tar.gz","compress":true},"hostnames":["sit0001red0"]}'

Response

{
  "id": 1781998,
  "type": "RVC3",
  "status": "pending",
  "message": null,
  "trigged_by": "test.user",
  "parameters": {
    "method": "kvm.full_backup",
    "params": {
      "hostname": "kvm1",
      "filename": "kvm1_doc-test.tar.gz",
      "compress": true
    },
    "update_rpm": true,
    "hostnames": [
      "sit0001red0"
    ]
  },
  "time_started": "2026-10-11T21:34:52Z"
}

Example 2: Retrieving the payload from the RVC job.

This example retrieves the payload from RVC job ID 1781998.

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

Response

{
  "id": 1781998,
  "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.full_backup",
    "params": {
      "hostname": "kvm1",
      "filename": "kvm1_doc-test.tar.gz",
      "compress": true
    },
    "hostnames": [
      "sit0001red0"
    ],
    "update_rpm": true
  },
  "time_started": "2026-10-11T21:34:52Z",
  "time_finished": "2026-10-11T21:34:53Z",
  "payload": {
    "sit0001red0": [
      {
        "result": "Starting full backup for kvm1",
        "timestamp": 1791754494
      }
    ]
  }
}