VMware vSphere

Overview

A VMware vSphere Protected Item backs up entire virtual machines from an ESXi host or vCenter Server at the hypervisor level, without installing a backup agent inside each guest. Magnus Box connects to vSphere over its management API, snapshots each selected VM, and backs up the VM configuration and virtual disks. This is an agentless, image-level backup of the whole VM.

Requirements

  • vSphere version: vSphere 6.7 (ESXi or vCenter) or later.
  • Backup agent platform: The Magnus Box backup agent must run on a Windows x86_64 machine.
  • Network placement: The machine running the backup agent must be on the same network as the target ESXi host or vCenter Server. For best performance, run the agent as a VM on the same ESXi cluster, or on the specific host, that it is backing up.
  • No temporary disk space: The machine running the backup agent does not require temporary local disk space for the backup to run.
  • Agent version: vSphere Protected Items require a recent version of the Magnus Box backup agent. If the VMware vSphere Protected Item type does not appear, update the agent to the current release.

vSphere permissions

Create a role (or use an account) in vCenter/ESXi that grants at least the following privileges. Missing privileges are the most common cause of connection and download failures.

  • Global: Enable/disable methods.
  • Datastore: Allocate space, Browse datastore, Low-level file operations.
  • Virtual machine > Provisioning: Allow read-only disk access, Allow virtual machine download.
  • Virtual machine > Snapshot management: Create snapshot, Remove snapshot.

Magnus Box connects using vSphere's SOAP API (VADP) and transfers virtual disk data over the NBDSSL protocol. Changed Block Tracking backups use NBDSSL with fastlz compression.

Add a vSphere Protected Item

  • In the backup agent, add a new Protected Item and select VMware vSphere as the type.
  • Under Connection, choose vSphere API and click Configure.
  • Enter the connection details:
    • Server: the ESXi host or vCenter address. To use a non-default port, enter it as host:port.
    • Username and Password: an account with the roles listed above.
    • Thumbprint (optional): supply the server's SSL thumbprint for certificate verification, or enable the option to accept an invalid SSL certificate.
  • Click Test Connection to confirm the agent can reach vSphere and authenticate.

[SCREENSHOT: Protected Item type list with "VMware vSphere" selected]

[SCREENSHOT: vSphere API connection dialog showing Server, Username/Password, thumbprint, and accept-invalid-certificate fields with a Test Connection button]

Select virtual machines

Click the plus sign to open the VM list and choose what to protect. Select the top-level VMware vSphere entry to back up all virtual machines, or expand the tree and select individual VMs. Selecting the top level automatically includes VMs added to the environment later.

[SCREENSHOT: Virtual machine selection tree with the top-level "VMware vSphere" node and individual VMs]

Backup modes and Changed Block Tracking

Choose how each backup captures VM state:

  • Latest VM state (Changed Block Tracking): Recommended for best performance. Backs up only the disk sectors that changed since the last successful backup. This option can be selected even for the first backup job. Performance is further optimized by skipping over unallocated disk sectors.
  • Latest VM state (Standard): Backs up the current state of all disks and the VM configuration. Past snapshots are flattened into the result.

In both modes, Magnus Box backs up the VM's vmx configuration file, its vmdk virtual disks, and related files. Separate snapshot files are not included in the backup. If a VM is running off a snapshot at backup time, the resulting disk is a flattened version of the snapshot branches.

[SCREENSHOT: Backup mode selector showing "Latest VM state (Changed Block Tracking)" and "Latest VM state (Standard)"]

Restore

Restore the VM's files (the vmx configuration, vmdk disks, and other files) to a local folder, then import the VM into vSphere:

  • Restore the VM files to a local disk on the machine running the backup agent.
  • Copy the restored files to an ESXi datastore.
  • Import the VM from the ESXi or vCenter interface.

Notes on restored disks and configuration:

  • Virtual disks are restored as thick-provisioned disks and expand to their maximum size. Optionally reclaim space with vmkfstools -K <vmdk>.
  • Update the VMX configuration to reference the restored disks, for example scsi0:N.fileName = <file>.
  • If CBT was enabled on the source VM, disable and re-enable (or restart) CBT before the first boot of the restored VM.
  • Granular file and folder restore from within the VM's disks is available for supported filesystems.

[SCREENSHOT: Restore dialog for a vSphere Protected Item showing restore-to-local-disk and granular file/folder options]

Limitations and notes

  • Independent disks are skipped. Disks in independent mode (persistent or non-persistent) do not support snapshots and are skipped during backup.
  • Snapshots are flattened. The backup captures the VM's current state; the snapshot tree itself is not preserved.
  • Windows agent only. The backup agent that runs vSphere Protected Items must be on Windows x86_64.

Troubleshooting: enable Changed Block Tracking inside vSphere

If backups report that CBT is not enabled, turn it on at the VM level:

  • Power off the VM.
  • In the vSphere web interface, click Edit for the VM.
  • Go to VM Options > Advanced > Configuration Parameters > Edit Configuration.
  • Set ctkEnabled to TRUE.
  • Set scsix:x.ctkEnabled to TRUE for each attached disk.
  • Power the VM back on.

To disable CBT, set the same parameters to FALSE and delete the VM's *-CTK.VMDK files.

Troubleshooting: collect diagnostic logs

To capture a verbose log for a failing backup:

  • Start the backup job manually.
  • On the storage destination selection step, tick Show advanced options.
  • Change Log Level from Default to Debug.
  • Run the job and review the more detailed job log.

Common errors and warnings

  • No parent snapshot found. Fallback to full backup. No valid reference backup exists yet (first backup, or the previous job failed). The next CBT backup will run incrementally.
  • VM contains [N] snapshots. Snapshots will be flattened during backup. The VM is running off a snapshot. Its current state is backed up, but the snapshot tree is not preserved.
  • Unable to run CBT: disk size changed. A disk was resized since the last backup. The job falls back to a full backup.
  • Unable to run CBT: inconsistent change id. The change ID is no longer valid. The job falls back to a full backup.
  • Unsupported disk mode [mode]. An independent-mode disk cannot be snapshotted and is skipped.
  • Error downloading file: 401 Unauthorized. The account is missing one or more Datastore privileges. Review the vSphere permissions above.
  • CBT is not enabled on [vm name]. CBT is off on the VM even though the Protected Item is set to Changed Block Tracking. Enable CBT inside vSphere as described above.

Need help?

If a vSphere backup keeps failing after checking permissions and CBT, contact support@magnusbox.com with the Debug-level job log attached.

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us